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Preface 


This manual describes the macro instructions provided by @ Asamuic program: showing bow macro instructions are 
the IBM System/3 Model 15. The publication is intended 

for persons who are programming in the Basic Assembler 

Language or its equivalent and who are famiisar with tie 3 
concept of macro instructions and sysiem programming 

for the IBM System/3 Model 15. 








The following topics are discussed in this publication: 


@ Coding macro instructions. 


mation which tu:the: 





manual! 


@ Descriptions of the various macro instructions 





ariier Heference Manual, 
@ OCL necessary to cail the macro process: 


@ Error conditions detected by the macro processor. 
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A macro instruction is a source statement that causes 
generation of a predetermined set of assembler statements 


each time the macro instruction is used. The Model 15 System 


Control Program provides macro instructions which per- 
form both system services and input/output device support. 
By using these macro instructions, you can perform both 
system and input/output operations with less coding. 


Figure 1 is an overview of the operation of the macro 
processor. The OCL statements used to call the macro 
Processor are explained in Chapter 3: OCL and Sample 
Program. 


WRITING MACRO INSTRUCTIONS 


You code macro instructions as follows: 


Starting 
Column 1 8 14 72 

























Symbol Macro No operands Any nonblank 
or blank name Or one or more | character if 


continuation is 
being used 


separated by 
commas 






The name field can contain any valid assembler language 
symbolic name beginning in column 1. The name is 
assigned to the first byte of generated code. Since the name 
is optional, it is shown enclosed in brackets. 


The desired mnemonic operation code (macro instruction 
name) must appear as specified in the macro instruction 
description. The operation code must start in column 8. 


Keyword 
Dash 





Parameter 
[Name] } $FIND NAME-module[,FIND-address {,PACK-P/S] 
=~_— 





Default 
Operand Value List 


Operand Optional Option 


Chapter 1: Introduction 


Operands specify the available services and options. The 
operands must start in column 14, and are written as 
follows: 


@ Each operand consists of a keyword followed by a dash 
and a parameter. 


@ Commas separate the operands; no blanks should be 
left between operands. 


®@ Keywords — those shown in capital letters — are coded 
exactly as shown. The keyword part of each operand 
must correspond to one of the keywords in the macro 
instruction description. 


@ The parameter part of the operand must immediately 
follow the dash. 


@ Parameters — those shown in lowercase letters — indicate 
information you must supply. Some operands are not 
required. These optional operands are indicated by 
enclosing the operand within brackets [KEYWORD- 
parameter]. 


® An option list for a keyword parameter is specified as 
follows: 


KEYWORD-A/B/C 


This list indicates that the keyword has the options 
A, B, or C. These are the only valid options for the 
keyword parameter. 


When the options Y/N are given in a macro instruction, 
Y indicates a yes response, N indicates a no response. 


@ The operands may be written in any order. If a key 
word is not specified, the default value is used. A 
default value is selected for optional keywords that are 
omitted. The default value is indicated in the macro 
instruction description by a line under the default option. 
For example, [KEY-A/B/C] indicates the option A is 
the default value. 
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This is your program. 
It includes macro 
statements. 







= 


J LO 
a This indicates the beginning 


of the next job. 






Source 


This indicates the end of your job. 
Statements 







OCL 
Statements 






{BM System/3 Model 15 
Macro Processor (SMPXDV) 














The macro processor reads source state- 
ments from either the system input de- 
vice or a source library. 






Load the macro processor ($MPXDV). 
OCL can be entered through the 
system input device or called from 
the procedure library. 











—_— 


@ All valid assembler statements and 
comments are placed in $SOURCE. 









Macro statements are listed in 
SSOURCE, preceded by an 
asterisk and followed by the 
macro expansion. 








Macro expansion statements are 
marked (by the macro processor) in 
position 96 in $SOURCE and indi- 
cated on the assembly listing by a 
plus sign (+) preceding the expan- 
sion statement. 












Invalid statements are flagged and 
placed in $SOURCE. 





$SOURCE 
File 


Statements placed in 7 
SSOURCE are used as 
source input to an 
assembler. 


Figure 1. Macro Processor Overview 
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Introduction 3 


SYSTEM CONFIGURATION 


The minimum system configuration for using the Model 15 
Macros is: 


@ 5415 Processing Unit with at least 48K bytes of main 
storage. 


© 3277 Display Station Model 1 with Feature 4632. 
This comprises the IBM System/3 Model 15 CRT/Key- 
board, usually referred to in this manual as the CRT/ 
Keyboard. 

@ Disk Storage Device. 

@ Asystem input device. 

@ 1403 Printer Model 2,5, or N1. 

The following input and output devices are supported: 

@ 5424 Multi-Function Card Unit (MFCU) Model Ai or 
A2, 1442 Card Read Punch Model 6 or Model 7,0r 
2560 Multi-Function Card Machine (MFCM) Model A1 
or A2. 

® 1403 Printer Model 2,5, or N1. 

@ 3277 Display Station Model 1 with Feature Number 
4632 (CRT/Keyboard). This device can be used both 
as the system input device and the system log device. 

@ 3410/3411 Magnetic Tape Subsystem Model 1,2, or 3. 

®@ 2501 Card Reader Model A1 or Model A2. 

@ 3284 Printer 


@ 3741 Data Station Mode 1 or 2 or Programmable Work 
Station Model 3 or 4. 


@ Disk Storage Requirements. 






SCi 
Minimum 15A | 15B | 15C 
5444 Disk Storage Drive, [ x | ” 
Mode! A2 
3340 Direct Access Storage x 
Facitity, Mode! A2 


Optional 


5444 Disk Storage Drive, x 
Model A3 

5445 Disk Storage, Models 1, x 
2,and 3 

3340 Direct Access Storage x 
Facility, Models 81 and B2 

3344 Direct Access Storage, 
Model A2 
























rege es ell 


‘Mutually exclusive 


The macro processor operates under coitrol of the 1BM 
System/3 Model 15 System Control Program. 


MACRO INSTRUCTIONS PROVIDED 


The macro instructions provided by the Model 15 System 
Control Program (SCP) and the functions they perform are 
shown in Figure 4. 


All macros you want to use must be in the source library on 
the program pack or the system pack. The program pack is 
the disk pack from which the macro processor is loaded. 
The system pack is the disk pack from which initial program 
load (IPL) is performed. Note that the macro processor and 
IPL. code may be on the same pack. 


You may want to delete some macro instructions from 
your library to reduce the amount of disk space required 
for the macro instructions. For instance, if your system 
does not include the 3410/3411 Magnetic Tape Subsystern, 
the tape macro instructions would be of no use to you. 
You can delete macro instructions from your library by 
using the library maintenance utility program, SMAINT. 




















Macro 
Instruction 
Device Type Supported Name Function 
System Reader SRLST Generate reader parameter list 
$RLSD Offsets in reader parameter list 
$READ Linkage to system reader 
System Log ‘| $LWTO Generate parameter list for WTO or WTOR 
SLMSG Generate parameter list for halt message on system log 
$LOG Linkage to system log 
| $LOGD Offsets in log parameter list 
General SCP | SROLL Rollout/rollin linkage (6704-SC1 Only) 
$FIND Find a directory entry 
SLOAD Load a module 
SFTCH Load a module and pass control 
$XCTL Load a module and exchange control 
$TRL Generate a translate parameter list 
STRTB Generate a translate table 
STRAN Generate an interface to the translate routine 
$SNAP Snap dump main storage 
SDATE Retrieve system date 
ST!OB Generate timer |OB 
$SiT Set interval timer 
STOD Return time of day and system date 
$RIT Return amount of time left in timer interval 
$EOJ End of job 
General |/O $ALOC Allocate disk space or device 
SOPEN Prepare an 1/O device 
SCKL Generate a checklist 
$CHK Check for 1/0 completion for BSCA operations 
$CLOS Prepare a device for termination 
S$DTFO DTF offsets for all devices 
$COMN Generate equates 
Card $DTFC Define the file for a card device 
$GETC Construct a card GET interface 
$PUTC Construct a card PUT interface 
$GPC Construct a GET or a PUT interface to a card file 


Figure 4 (Part 1 of 2). Macro Instructions 
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Macre i 
Instruction | 
Device Type Supported Narne 1 


Punetios 


Printer SDTFP : Define the file for oceania 


Constroct aprinter Phi] interface 


[ 
| 
| 


SPUTP 


$GETD 
SPUTD 


I 
_ = { 
Disk $DTFD | Nefine the file for disk 
Construct a disk GET interface 


Constroet a disk PLUPE interface 


Caenerate a chet fp mloek 


$IOBD ! 
| 
SIOED 
$RDD Read froin efiels 


Generic .isptean ai ie block faa disk 


Wirjte peo vtisk 


SWRTD 
SWAIT 


Wait tor disc 1/0 conupieiion 


Define tie t. 


Tape SDTFT efor tae 

SGETT Construct a tane GEE interface 
SPUTT i Congtrust a tape PLP iniartace 
$RDT 
SWRTT : Write to tape 
i SCTLT 
SWTT 


Read trom fape 


Contiealcommianad tor tape 


Walt foe tape tt? completion 


$GETI 
$PUTI 


item a 2 1 ht a ae nme ne ree he pecan erste ener eo 


Constrisct a tevice independent GET interface 


5 
| 
! 

as ; i 2 

Device Independent SDTFI i Define a device independent file 
| 
i Spe 
| Constpuet sy deviee inderendent PUT interface 
i 
i 


CRT/Keyboard SDIFS : Rietine the Pie fy OPE 


SGETS : Consthuct a keyboard GEE Sitertace 





S$PUTS i Soaesternag SRE inrerface 
$PGS 
SCOEP 


Construct «# PUT thei a GET vecquest to CRT/Keyboard 


Generate « parameter list for a program furiction key request 





i 
{ 

| 

\ 

| Prograna foro key POCHIOGT 

{ 

: . 

| rest Mo oroGeam funetian hey miessoct 


ilefine thee tlic ter Vea y 





: 
i 
| Gonstrue: a 3/41 GE interface 
i 


Coasteget< “747 NIT interface 








Figure 4 (Part 2 of 2). Macro Instructions 


You code macro instructions to generate a block of 
assembler statements that perform a certain function. Some 
functions may be the same each time they are used, others 
may be modified by specifying different operands. This 
chapter explains the System/3 Model 15 macro instructions 
in detail. 


The macro instructions are grouped in this chapter accord- 
ing to the functions they perform: 


@ System services 
@ Input/output support 


Input/output support macro instructions are further 
divided according to the device supported. 


PROGRAMMING CONSIDERATIONS 


When you use the macro processor you should remember 
the following restrictions: 


1. The generated code for some macro instructions uses 
register 1; the generated code for other macro instruc- 
tions uses register 2. You should save the contents of 
the register used by the generated code before issuing 
the macro instruction; otherwise, the contents are 
destroyed. These macro instructions use register 1: 


$PFKY 
$PFKT 
$RDD 
$TRAN 
SWAIT 
$WRTD 


These macro instructions use register 2: 


$ALOC $GETT $PUTS 
$CHK $GPC $PUTT 
$CLOS $LOAD $RDT 
$CTLT $LOG $READ 
$DATE SOPEN $RIT 
$FIND $PGS SSIT 
$FTCH $PUTC $TOD 
$GETC $PUTD SWRTT 
$GETD SPUTI SWTT 
$GETI $PUTK $XCTL 
$GETK $PUTP 

$GETS 


Chapter 2. Macro Instruction Statements 


2. The code generated by the macros is assigned labels, 
which begin with the dollar sign ($). To avoid dupli- 
cate label errors, you should not use the dollar sign 
as the first character of a label. 


SYSTEM SERVICES MACROS 


By using system services macro instructions, you can com- 
municate with the Model 15 system control program. 


These macro instructions can do the following: 

@ Read records from the system input device. 

@ Log and write error messages. 

@ Determine the location of an object module on disk. 


® Obtain object modules from disk and load them into 
main storage. 


@ Pass control to modules in main storage. 
@ Terminate the current job. 


The system services macro instructions are divided into 
three groups: 


1; System reader macro instructions, which provide 
support and linkage to the system reader function. 


$READ 
$RLSD 
$RLST 


2. System log macro instructions, which provide support 
and tinkage to system log functions. 


$LMSG 
$LOG 

$LOGD 
$LWTO 
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3. General SCP macro instructions, which provide 
linkage to system functions. 


$DATE 
$EOJ 
SFIND 
$SFTCH 
$LOAD 
$ROLL (5704-SC1 only) 
SRIT 
$SIT 
SSNAP 
STIOB 
$TRAN 
$TRL 
$TRTB 
$TOD 
$XCTL 


System Reader Support 


You read a record from the system reader by calling the 
system reader routine through the $READ macro instruc- 
tion, The system reader may be one of the following: 


@ CRT/Keyboard. Only 96-byte, single-buffered input is 
allowed for this device. Double buffering is ignored. 


e@ 2501 Card Reader. Single and double buffering are 
supported. Only 80 bytes of the 96-byte buffer are 
used as input; the remaining 16 bytes are cleared to 
blanks. 


@ 2560 Multi-Function Card Machine (MFCM). Single and 
double buffering are supported. Only 80 bytes of the 
96-byte buffer are used as input; the remaining 16 bytes 
are cleared to blanks. Support for both the primary 
(MFCM) and secondary (MFCM2) hoppers is provided. 


@ 1442 Card Read Punch. Single and double buffering are 
supported. Only 80 bytes of the 96-byte buffer are used 
as input; the remaining 16 bytes are cleared to blanks. 


@ 5424 Multi-Function Card Unit (MFCU). Both single and 
double buffering are supported. Support for both the 
primary (MFCU1) and secondary (MFCU2) hoppers 
is provided. All 96 bytes are used as input. 


@ Directly attached 3741 Data Station Model 1 or 2 or 
Programmable Work Station Model 3 or 4. Single and 
double buffering are supported. Only 96-byte records 
may be read. 


To call the system reader, you must do the following: 


1. Use the SRLST macro to construct a parameter list as 
input to the system reader routine. 


2. Use the SRLSD macro instruction to establish equates 
for the system reader parameter list. 


3. Issue the SREAD macro instruction. 


The SREAD macro generates the code to load the parameter 
list address into register 2, set the operation code, call the 
system reader routine, and check the return codes. Because 
the return code is in the same byte as the operation code, 
the operation code must be reset before each call, The 
$RLSD macro is provided to generate the offsets into the 
parameter list, the values for the operation codes, and the 
values for the return codes. 


Generate a System Reader Parameter List (SRLST) 
This macro instruction generates a reader parameter list. 


The format of the SRLST macro instruction is: 


IName]} SRLST | BUF 1-address,WORK-address|,BUF 2-address ] 








BUF 1-address specifies the address of the leftmost byte of 
a 96-byte buffer that is aligned on a 128-byte boundary. 
This operand is required. 


WORK-address specifies the address of the leftmost byte of 
a 47-byte work area; this operand is required. 


BUF 2-address specifies the address of the leftmost byte of 
a 96-byte buffer that is aligned on a 128-byte boundary. 
This is the second buffer if double buffering is used: if this 
operand ts not specified, single buffering is assumed. 


System Reader Parameter List Offsets (SRLSD) 


This macro instruction generates a list of equates used to 
label the fields in the system reader parameter list. $RLSD 
also generates the operation codes and return codes used 
by $READ. To avoid duplicate labels, you should use this 
macro instruction only once in a program, 


The format of the $RLSD macro instruction is: 


[a 


Linkage to System Reader Function (SREAD) 


This macro instruction generates the linkage to call the 
system reader function and check for return codes. 


The format of the $READ macro instruction is: 


{[Namel| $READ] [LIST-address}] [,OPC-code] [,EOF-address] 
[,EOJ-address] [,ERR-address] 





LIST-adadress specifies the address of the leftmost byte of 
the system reader parameter list. 1f this operand is not 
specified, the address of the parameter list is assumed to be 
in register 2. 


OPC-code specifies the operation code for this read request. 
The allowable codes and their meanings are: 


Code Meaning 

RD Set the operation code to read one record 
from the system reader single buffer. 

RDF Set the operation code to read one record 


from the system reader into buffer 1 and 
start a read on buffer 2. 


RDD Set the operation code to wait on buffer 2, 
switch the buffers, and start the other 
buffer. 

ROL Set the operat.u.. code to wait on buffer 2, 


and switch the buffers; do not start the 
other buffer. 

N Do not set any operation code. If this value 
is specified, it is your responsibility to set the 
operation code before issuing this macro. 


The default value for this operand is RD. 


EOF-address specifies the address in your program that re- 
ceives control when an end-of-file statement (/*, /&, or /.) 
is detected. If this operand is not supplied, no code is gen- 
erated to check for the end-of-file condition. 


EOJ-address specifies the address of the routine that should 
get control if an end-of-job or end-of-step statement (/& or 
/.) was detected on the previous read. If this operand is not 
specified, the test for the return code is not generated. 

Once a /& statement is read from the system reader, nothing 
can be read from the system reader until the end of step. 
Once a /. statement is read from the system reader, nothing 
can be read from the system reader until the end of job. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent 1/O error. \f this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


Notes: 

1. lf ERR or EOF addresses are not specified, you should 
check the return code in your program to determine the 
outcome of the operation. 

2. When double buffering is used, return code should be 
provided to return to the read macro instruction until 
end-of-file (EOF) is received. When the program’s EOF 
is dependent upon a user-defined EOF statement, the 
last request to the read macro should be a wait only call; 
this will allow all outstanding read requests to be cleared 
from the device queues. The last wait request is necessary 
to prevent overlaying the system input work area before 
the program reaches end of job. 


System Log Support 


Specifying a $LOG macro instruction in your program gen- 
erates a call to system log (system log is a group of system 
output routines which provide communication with the 
operator). You may want to use system log to notify the 
operator of error conditions, error recovery procedures, and 
the validity of previous operator responses to messages. 

If the operator selects an invalid option in response to a 
message, the response is not accepted by system log. 
Instead, another message is issued to the operator until a 
correct option is taken. 


Note: When an immediate cancel (option 3) is selected, 
control is passed directly to the end-of-job (EOJ) routine 
by system log. 


Two types of printed output are available through system 
log — logs and messages. Both are printed on the system 
log device. 


@ A /og is a four- or six-character statement that identifies 
the type and source of an error. 


@ A message is a printed statement which can be used to 
indicate errors that have occurred or to issue instructions 
to the operator, such as requesting that a disk file be 
placed on a certain drive. 


Logs and messages can be issued with or without being 
displayed on the 3277. 


Three devices can be used as the system log device: the 
1403 printer, the 3284 printer, or the CRT/Keyboard. 
You can change devices by entering a LOG statement in 
your job stream. 
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To use system log, you must do the following: 


1. Build the log parameter list using the $LWTO or 
$LMSG macro. 


2. Use the $LOGD macro instruction to establish equates 
for the log parameter list. 


3. Issue the macro instruction: 


[Name] | $LOG [LIST-address] [,OPNO-address] 
{,OPN1-address] [,OPN2-address] 





4. Process the operator's reply in your program. 


Two types of messages can be displayed on the log: the 
system message and the message to the operator. 


The $LMSG macro instruction generates a parameter list to 
display the standard system message. You can also include 
from 1 to 107 characters of text with this message. The 
Operator can respond to this message by pressing the PF12 
key, taking one of the four allowable options, then pressing 
ENTER. Option 0, 1, or 2 is returned to you for checking; 
option 3 means end-of-job. If the Operator takes option 3, 
the system log routine goes directly to the end-of-job. 


The $LWTO macro instruction generates a parameter list to 
display a message to the operator. This message is from 1 
to 107 characters long and is prefixed with six characters 
which you specify using the $LWTO macro. You can re- 
quest a reply (1 to 72 characters) from the operator, but if 
no reply is requested, the operator responds to the message 
by pressing PF12, then ENTER. 


For either of the message types, the $LOGD macro instruc- 
tion is specified to generate offsets into the parameter list 
and to define the meaning of the fields within the Parameter 
list. 


Text Length Considerations: Message text is displayed on 
the CRT in one, two, or three 36-character lines, depend- 
ing on the text length. For example, if the text length is 

60 characters, it takes one line of 36 characters and 24 char- 
acters from the second line to display the message. 


Reply Length Considerations Three, 36-character lines (107 

characters plus the CRT control character) are available for 

the message and reply. The number of characters allowed 

for the reply depends on the number of lines that contain 

test characters. Once a test character has been entered on 

a line, any non-text positions of that line cannot be used 

for a reply. Instead, the reply must begin on the next line. 

If the third line contains a text character, no reply can be 

made. For example: 

If the text length is: The reply length can be: 

more than 1 character 
but less than 36 

more than 36 characters 
but less than 72 

more than 72 characters 
but less than 108 


from 1 to 72 characters 
from 1 to 36 characters 


no reply can be made 


Generate a Parameter List for WTO or WTOR ($L WTO) 


This macro instruction generates a system log parameter list 
for the write-to-operator or write-to-operator-with-reply 
function. 


The format of the $LWTO macro instruction is: 


[Name] | $LWTO] TLEN-number, TADR-address [,COMP-code] 
[,HALT-code] [,SUBH-code] [,REPLY-Y/N] 


[,RLEN-number] [,RADR-address] 





TLEN-number specifies the text message length (an un- 
signed, non-zero, decimal value). This operand is required 
and can be from 1 to 107 characters long. 


TADR-address specifies the address of the leftmost byte of 
the text message; this operand is required. 


COMP-code specifies the first two characters of the halt 
message. These characters are the component identification. 
If this operand is not specified, the default value is two 
blanks. 


HALT-code specifies the second two characters of the halt 
message — the halt identification. If this operand is not 
specified, the default value is two blanks. 


SUBH-code specifies the last two characters of the halt 
message — the subhalt identification. If this operand is not 
specified, the default value is two blanks. 


REPLY-Y or N specifies whether or not a reply is requested. 
If Y (yes) is specified, system log waits for the operator to 
reply. If N (no) is specified or if this operand is omitted, no 
reply is allowed. 


RLEN-number is the length of the reply (an unsigned, non- 
zero, decimal value, from 1 to 72). 1f REPLY-Y is specified, 
this operand is required. 


RADR-address specifies the address of the leftmost byte of 
the reply area. If REPILY-Y is specified, this operand is 
required. 


Generate a Parameter List for Message on System Log 
($LMSG) 


This macro instruction generates a system log parameter 
list for a log and/or message to the operator. 


The format of the $LMSG macro instruction is: 


[FORMAT-code] [,COMP-code ] 
{,HALT-code| [,SUBH-code! {,SEV-codej 
[,DEF-code] |,OPNO-Y/N) [,OPN1-Y/N} 
{,OPN2-Y/N] |,OPN3-Y/N] [TLEN-number ] 
{, TADR-address} 
















FORMAT-code specifies the type and length of the system 
log parameter list. The valid code values and their meaning 
follow: 


Code Length of List Format of List 

A 7 bytes FDCCHHO 

B 9 bytes FDCCHHOII 

C 10 bytes FDCCHHOL AA 
D 12 bytes FDCCHHOUTLAA 


where: F and D are flag bytes 

CC is the component ID 

HH is the message ID 

O is the option indicator (this is determined 
by the settings of operands OPNO, OPN1, 
OPN2, and OPN3) 

I! is the sub-halt 1D 

L is the length of the text 

AA is the address of the text 


If this operand is omitted, FORMAT-B is assumed. 


COMP-code specifies the first two chatacters of the message 
the component description (CC). lf this operand is nes 
specitied, two blanks are assumed, 


HAL 7 -code specifies the second two characters oi the 
message --- the message identification (HH). If this aperand 
is not specified, two blanks are assumed. 


SUBH code specifies the last two characters of the message 
the subhalt identification (1). If FORMAT Bot — 

was specified and this operand is omitted, two flanks are 

assumed. 


SEV -code specifies the severity which conditions the selec- 
tion of the default (DEF) option operand. This entry cor- 
responds to the severity code entry in the NOHAL.7 state- 
ment. If the severity code specified in the NOHALT state 
ment is fess than the value specified in this entry, the halt 
will be issued. Valid entries (from lowest to highest severity) 
are 1,2, 4, and 8. If this operand is omitted, a severity of 
8 is assumed. 


DEF-cade specifies the default option to select when execut- 
ing in unattended mode. Valid entries ate N, 0, 7, 2, and 
3: if this operand is not specified, N (none) is assumed. 


OPNO-Y/N specifies whether option 0 is allowed. If Y 
(yes) is entered, option O is allowed; if N (no) is entered or 
if this operand is omitted, option O is nut allowed. 


OPN1-Y/N specifies whether option 1 is allowed. IY is 
entered, option 1 is allowed; if N (no) is entered or if this 
operand is omitted option 1 is not allowed. 


OPN2-Y/N specifies whether option 2 is allowed. lf ¥ 
(yes) is entered, option 2 is allowed; if N (no) is entered an 
if this operand is omitted, option 2 is oot allowed 


OPN3-Y/N specifies whether option 3 ts allowed. If Y (yes) 
is specified, option 3 is allowed; if N (no) is specified or if 
this operand is omitted, option 3 is not ailower. 


Note: If aption 3 is allowed, control will net be returned 
to your program. 
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TLEN-number specifies the text length. This entry (L), 
which is a decimal entry from 1 to 107, is required if 
FORMAT-C or D is specified. 


TADR-address specifies the leftmost byte of the text 
address. This operand (AA) is required if FORMAT-C or D 
is specified. 


Generate the Linkage to the System Log (SLOG) 


This macro instruction generates the linkage required to use 
the system fog function, and checks the response returned. 
The $LOGD macro instruction must be used with this 
macro instruction, to establish offsets in the system log 
parameter list. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $LOG macro instruction. 


The format of the $LOG macro instruction is: 


[Name] | $LOG {L.1ST-address] {,OPNO-address] 
[,OPN1-address] [,OPN2-address] 





LIST-address specifies the address of the leftmost byte of 
the system log parameter list. If this operand is not speci- 
fied, the address of the parameter list is assumed to be in 

register 2. 


OPNO-address specifies the address of the routine that 
should receive control if option 0 is taken. If this operand 
is not specified, no check is made for a response of 0. You 
would use this operand only if the $LMSG macro was used 
to generate the parameter list. 


OPN 1-address specifies the address of the routine that 
should receive control if option 1 is the response. If this 
operand is not specified, no check is made for a response of 
1. You would use this operand only if the $LMSG macro 
was used to generate the parameter list. 


OPN2-address specifies the address of the routine that should 
receive control if option 2 is taken. If this operand is not 
specified, no check is made for a response of 2. You would 
use this operand only if the $LMSG macro was used to gen- 
erate the parameter list. 


Generate Displacements for System Log ($LOGD) 


This macro instruction generates the field iabeis and offsets 
for the system log parameter fists. To avoid duplicate labels, 
you should use this macro instruction only once in a program. 


The format of the $LOG macro instruction is: 


General SCP Support 


The general SCP macro instructions alicw you to previde 
linkage to system functions by communicating with the 
Model 15 system control program. 


Roilout/Rollin Linkage (SROLL) 
This macro applies to Program Number 5704-SC1 only. 


You use $ROLL to interrupt (roll out) the current program 
so that another program can be executed. When the second 
programm is finished, the first program is reinstated (rolled 
in) and continues executing. 


Once rollout is initiated, the CRT/Keybuard becomes the 
system input device until otherwise specified by the user 
or until the interrupted program is rollec! in, 


When using rollout, you should follow these procedures: 


1. Note the following restrictions: 

a. A program using $ROLL can execute in either 
partition, but will acknowledge the rollout request 
only when running in partition 1. 

b. A program using $ROLL must he so defined to the 
linkage editor using the ATTR parameter in the 
OPTIONS statement (see /BM System /3 Overlay 
Linkage Editor Reference Manual, GC21-7561). 

c. If the interrupting program also recognizes rollout 
requests, these requests will be ignored. 

d. The same !/O devices are available to the interrupt- 
ing program as were available to the original pro- 
gram with exception of tape units. 

e. Whenever an interrupting program shares the same 
disk files as a rolled-out program, only reading 
and updating are allowed by the two programs. 
Loading and additions are not allowed. 
updating are allowed by the two programs. Load- 
ing and additions are not allowed. 


2. Issue the $ROLL macro instruction: 


The coding generated by the $ROLL macro instruc- 
tion determines whether rollout has been requested 
by entering the ROLLOUT operator control com- 
mand. If rollout has not been requested, the current 
program continues executing. If the request is pend- 
ing the rolfout routines are called. Rollout performs 
the following steps: 

a. Places the current program (program being exe- 
cuted and the current contents cf the scheduler 
work area on disk. 

b. Allows a new program or procedure to be run in 
place of the current program. 

c. Reloads the original program and restores the 
previous contents of the scheduler work area 
and passes control to the point where the orig- 
inal program was interrupted. 


The format of the $ROLL macro instruction is: 


(Name] (INDEX-1/2] 


INDEX-1/2 specifies which register can be used in the 
macro instruction. If this operand is omitted, register 2 is 
used. 


Find a Directory Entry (SFIND} 


A load module must be in the object library. Specific infor- 


mation must be obtained from the module’s object library 
directory entry before a load or fetch can be performed. 
There are two ways you can locate a load module and ob- 
tain the information: 


@ Issue a $FIND before issuing a $LOAD, Form Il. The 
information obtained during the find is used during the 
load operation. 


@ Issue a load with find (SLOAD, Form |), a fetch 
(S$FTCH) or a fetch to address (SXCTL). These func- 
tions perform the find operation as part of their normal 
functions. 


The $FIND macro instruction searches the object library 
directory for the requested module name and returns the 
directory entry in the parameter list. 


If you will need to use the data in register 2 at a iater time, 
you should save the contents of that register before issuing 
the $FIND macro instruction. 


The format of the $FIND macro instruction is: 


[Name]] $FIND | NAME-module[,FIND-address] [,PACK-P/S] 


NAME-module provides the name of the module to be 
found. Only names of object modules (O modules) can 
be entered here. 


FIND-address specifies the label that becomes the address 
of a 12-byte parameter list built by the generated code. 
Initially the parameter list contains input to the supervisor. 
After execution, it contains the directory entry of the 
module. The format and contents of the parameter list 
after execution are shown in Figure 5. If this operand is 
not specified, a macro label is generated. 


PACK-P/S specifies the program disk pack (P) or the system 
disk pack (S) to be searched. If this operand is not specified, 
P is assumed. 


Load a Module ($LOAD) 


This macro instruction loads a module into storage at the 
address you specify. Contrci is returned after the module 
has been loaded. You may then pass control to the module 
at the specified address. If you will need to use the data in 
register 2 at a later time, you should save the contents of 
that register before issuing the SLOAD macro instruction. 
Two forms of this macro can be used: load with find and 
load only. 


Load with Find (Form 1!) 


The load with find macro instrtiction locates the module 
and loads it into main storage. 


The format of this macro instruction ts: 


[Name] | $LOAD |] NAME-module name [,F IND-address]} 


[,LOAD-2/address] [,USE-R/NR] 
[,PLIST-address]} LPACK-P/S} 
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Number 
Entry of Bytes 


Disk Address 2 1 










Displace- 
ment 





Description 


















Cylinder/sector address of the rnodule. 






Number ot Type O—Sector length of the module in hexadecimal 


text sectors 1 2 Type R--Category of routine 








Link edit Hexadecimal storage address at which the module was linkage edited. 
address 2 4 See note 2. 







Displacement 


Number of bytes, in hexadeciinal, into the first sector containing RLDs, 
of RLDs | 5 


of the first relocation directory (RLD) entry of the module. 







Entry point 





Hexadecimal storage address at which program execution begins {with- 
address 2 7 out RLDs). 







Storage size 1 8 Amount of storage (in sectors) required to execute the program. 


















Attributes 2 A Byte 1: 
Bit 0 1 = Permanent entry 
0 = Temporary entry 
1 1 = Inquiry program 
2 1 = Rollout-evoking program (5704-SC1 only) 
1 = External buffers (if byte 2, bit 1 = 1) 






(5704-SC2 only) 
o 1 = Must run in dedicated environment 
(5704-SC1 only) 
Reserved (5704-SC2 only) 
= Requires source information 
= Deferred mounting allowed 
= PTF applied 
= Overlay object program 










NOoh 
= 3 wo 











Bit 0 1 = The system input device must be dedicated to 
this program 
j 1 = Checkpoint/Restart program 
1 = External buffers (if byte 1, bit 2 = 1) (5704-SC2 only) 
See note 1 
2 1 = This program will access the source file directly 
3 1 = Macro processor is allowed (5704-SC1 only) 
1 = Model 15D program (5704-SC2 only) 
4 1 = This is a privileged program 
5 1 = This program requires that a new ioad address be 






calculated at load time to place it in main storage 

beyond its own program common region 
6 1 = 3340 data management (5704-SC1 only) 

Reserved (5704-SC2 only) 
7 Memory resident overlays 


























Level 1 B 





Release version of this entry. 





See olla oe 


Notes: 
1. For 5704-SC2 the checkpoint/restart and external buffer attributes are mutually exclusive, 


2. For 5704-SC2, if the entry has the attributes for external buffers, the low-order byte of the link edited address 
contains the number of sectors minus 1. 









Figure 5. Find Parameter List Description 


Number Displace- 
of Bytes ment Description 


Disk Address Cylinder/sector address of the module in hexadecimal. See note 1. 


Number of 
text sectors Sector length of the module, in hexadecimal. 
Link edited 


address Storage address at which the module was linkage edited. See note 2. 


Displacement 


Hexadecimal displacement, in bytes, into the first sector containing RLDs, 
of RLDs 


of the first relocation directory (RLD) entry of the module. 


Relocated entry 
point address 








Storage address at which program execution begins, after resolving RLDs. 


Load address Address at which the requested module is loaded. 


Notes: 


1. la directory entry was not found ona load with find, the first byte contains a character O. 


2. For 5704-SC2, if the entry has the attributes for external buffers, the low-order byte of the link edited address 
contains the number of sectors minus 1. 





Figure 6. Find Parameter List after Load Execution 
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NAME-module name provides the name of the module to 
be loaded and is required. Only O modules can be 
specified. 


FIND-address becomes the address of the parameter list 
passed to the find routine. The parameter list is generated 
by the macro processor. After execution of the load, this 
parameter list contains the modified entry for the module 
as shown in Figure 6. 


LOAD.-2/address specifies the address where the module 
is to be loaded into main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


USE-R/NR indicates whether the code generated by the 


macro instruction is to be reusable (R) or nonreusable (NR). 


If the operand is not specified, NR is assumed. 


You can reuse the generated code to load the same module 
more than one time, or to load different modules. If you 
wish to load different modules using the same generated 
code, you should also specify the PLIST operand. 


PLIST-adadress is used only when the generated code is 
reusable. The address specified identifies the leftmost 
byte of a parameter list passed to the load routine. To 
load a different module using the same generated code, 
you must update the parameter list to indicate the desired 
module. Figure 7 shows the format and contents of the 
parameter list. 


PACK-P/S specifies the program disk pack (P) or the 
system disk pack (S) containing the requested module. 
If this operand is not specified, P is assumed. 


Number Displace- 
of Bytes ment 


Load Only (Form 11} 


The load-only macro instruction loads a module previously 
found by the $FIND macro instruction. The format of 
this macro instruction is: 


[Name] | $LOAD ] FIND-address {,LOAD-2/address} 
{,PACK-P/S] 


FIND.-address is the address used in the previous $F IND 
macro instruction. It identifies the directory entry of the 
module in main storage. After execution of the load, this 
address points to the directory entry of the module as 
shown in Figure 6. 


LOAD-2/address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


PACK-P/S specifies the program disk pack (P) or system 
disk pack (S) containing the requested module. 1f this 
operand is not specified, P is assumed. 


Load a Module and Pass Control! ($F TCH) 


The fetch macro instruction (SF TCH) finds a module in 
the directory, loads the module into main storage, and 
Passes control to it. Your program does not regain control. 
When a module is fetched into main storage, the relocation 
factor is added, as necessary, to the module’s link edit 
address. This determines the location in main storage 
where the module is loaded. The module receives control 
at its entry point. 


Description 





Module Type 
Module Name 
FE 


Load Address 


Figure 7. Load Parameter List Description 


16 


Must contain O to indicate an object module. 


The name of the module to be loaded. 


X'FE’ 


The address at which the module is to be loaded. 





if you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $F TCH macro instruction. 


The format of the $F TCH macro instruction is: 


[Name] | $FTCH Name-module name [,PACK-P/S] 


NAME-module name specifies the object module to be 
fetched into main Storage. The name must be the same as 
the name in the directory entry. 


PACK-P/S specifies the Program disk pack (P) or the 
system disk pack (S) containing the requested module. If 
this operand is not specified, P is assumed. 


Load a Module and Exchange Control! ($XCTL} 


This macro instruction finds a module in the directory, 
loads the module into main storage at the address you 
‘specify, and passes contro! to it. Control is not returned 
to your program. As with the $F TCH Macro instruction, 
relocation factors are resolved, and control is Passed to 
the entry point of the program. 


The format of the $XCTL macro instruction is: 


{Name]] $XCTL NAME-module name [,LOAD-2/address] 
L,PACK-P/S] 


NAME-module name specifies the name of the module to 


be loaded and given control. The module must be an O 
module. 





LOAD-2/address specifies the address where the module 
is to be loaded in main storage. The 2 indicates that the 
address is in register 2; the address is the symbolic address 
where the module is to be loaded. If this operand is not 
specified, 2 is assumed. 


PACK-P/S specifies the Program disk pack (P) or the 
system disk pack (S) containing the requested module. 
If this operand is not specified, P is assumed. 


Generate a Translate Parameter List (STRL) 


This macro instruction generates a parameter list needed 
by the Model 15 Translate routine. This list is called via 
the STRAN macro instruction. $TRL does not generate 
executable code. Figure 8 shows the format of the 
translate parameter list. 


Translate Routine Operation 


To use the Model 15 translate routine, you must provide a 
translate area. The format of the area is: 


Byte Field Description 


0 Byte contents used to determine whether a 
character is to be translated. 
1 Byte contents are substituted for characters 


that are not to be translated. 
2-257 256-byte translate table. 


The translate routine Processes a field, specified by the 
$TRAN macro instruction, one byte at a time. 


The translate table must be constructed so that the displace. 
ment (from the beginning of the table) of the translated 
representation of a character is equal to the hexadecimal 
representation of the untranslated character, (For example, 
if you want to translate X‘C1' to X‘41', you could 
construct a translate table in which the value at displace- 
ment X‘C1’ in the table is X‘41".) 


The contents of the byte at a given displacement are com- 
pared with the contents of the first byte in the translate 
area (byte 0). If an equal compare results, the character is 
considered to be invalid and the following actions are 
performed: 


@ The completion code in the Parameter list is set to indi- 
cate that an invalid character was detected. 


@ The hexadecimal value in the second byte of the trans- 
late area (byte 1) is substituted for the original character. 


If an unequal compare results, the hexadecimal value in the 
translate table is substituted for the original character. 


The format of the $TRL macro instruction is: 





[Name]] $TRL TO-address,FROM-address, LEN-number, 
TRT-address 
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TO-address specifies the symbolic address of the first byte 
of the data to which the translated data will be moved. 


FROM.-address specifies the symbolic address of the first 
byte of the data field to be translated. This address may 
be the same as the address specified in the TO operand. 


LEN-number specifies the decimal length of the FROM 
field. 


TRT-address specifies the symbolic address of the first 
byte of the translate area. 


All four operands are required. 


Generate a Translate Table ($TRTB) 


This macro instruction generates an EBCDIC to ASCII or 
an ASCII to EBCDIC translate table. The table is generated 
in the format required by the $TRL macro instruction, and 
can be addressed by $TRL when you translate data. 


The format of the $TRTB macro instruction is: 


(Name]] STATS | [CODE-E/A] [,HEX-hex] 


CODE-E/A specifies whether the character code of the 
data to be translated is EBCDIC (E) or ASCII (A). If this 
operand is omitted, EBCDIC (E) is assumed. If CODE-E 
is specified, STRTB generates a 258-byte table: if CODE-A 
is specified, $TRTB generates a 130-byte table, 


Note: \f you specify CODE-A, you may want to specify 
DC 128XL1‘FF’ after the $TRTB macro instruction to 
allow for invalid ASCI! characters. 


HEX-hex specifies the hexadecimal pattern with which to 
replace any invalid characters found during translation. If 
the HEX operand is not specified, the replacement char- 
acter is X’3F’ for EBCDIC or X‘1A’ for ASCII. 


Generate an Interface to the Translate Routine ($ TRAN) 


This macro instruction generates an interface to the Model 
15 translate routine. After the translate routine has 
finished, control is returned to your program with a com- 
pletion code in the translate routine parameter list. The 
address of the parameter list is in register 1. You should 
check the completion code to see if any characters that 
are not to be translated were encountered. 


The format of the $TRAN macro instruction is: 
owl seas Heese 


TRL-address specifies the symbolic address of the translate 
parameter list. If this operand is not entered, the address 

is assumed to be in register 1. See Figure 8 for a description 
of the parameter list. 


Field Description 





Address of the transtate area (your program must 

define the translate area) 

FROM field address, for transtation 

TO field address for translation 

Number of bytes to translate 

Completion code: 
X‘00' -translation complete, no errors 
X'FF’ —invalid character detected 





Figure 8. Translate Parameter List 


Snap Dump Main Storage (SNAP) 


This macro instruction provides an interface with the non- 
terminating system storage dump routine. You must 
specify a dump identifier and the limits of the area to be 
dumped. The contents of the specified main storage area 
are put on the 1403 printer. Output from the dump 
routine consists of: 


@ The specified dump identifier. 

@ The contents of register 1 (XR1), register 2 (XR2), the 
Instruction Address Register (IAR), the Program Mode 
Register (PMR), the Address Recall Register (ARR), and 
the Local Storage Register (LSR). 


@ The contents of the specified main storage area. 


Control is returned to the next sequential instructica in 
your program. 


The songs of the pete macro men eor is: 


[iva ame]] SSNAP | ID-hex,START-address, END-address | 


/D-hex specifies a 
as the dump identifier. 





é-byte hexadecimal number to be used 


START-adadress specifies the symbolic address of the low- 
storage limit of the area to be dumped. 


END.-address specifies the symbolic address of the high- 
storage limit of the area to be dumped. 


All three operands are required. 


Obtain System Date (SDATE) 


This macro instruction generates the code necessary to 
retrieve the system date and piace it at a specified location 
in your program. 


if you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the $DATE macro instruction. 


The format of the $DATE macro, instruction is: 
[LABEL-address] 


LABEL-address indicates the address of the leftmost byte 
of a six-byte area in which you want the system date 
placed. If this operand is not specified, the address at 
which you want the date to be placed is assumed to be in 
register 2. 








$DATE 


{Name] 


Generate Timer 1OB (STIOB) 


This macro instruction generates an 1OB jot the interval 
timer. STIOB must be used if you use SSIT, SRIT, or 
$TOD in your program. The format of the timer IOB is 
shown in Appendix C: Input/Output Blocks. 


The format of the $TIOB macro instruction is: 


[DATE-Y/N] 












$TIOB 





[Name] 





DATE-Y/N specifies whether a date field is to be generated. 
If this operand is not entered, N (no) is assurned. If the 
$TOD macro instruction is used in your program, Y (yes) 
must be entered. If DATE-Y is specified, use of the $SIT 
macro instruction destroys the date in the timer 1OB. 


Set Interval Timer ($SIT} 


This macro instruction sets the interval timer to cause a 
timer interrupt after the specified amount of time has 
elapsed. Before issuing this macro instruction you must 
place the desired interval in bytes 2-7 of the timer IOB. 
When the interval is set, byte 8 in the timer IOB is set to 
X‘00’. When the interval is expired, byte 8 is set to X‘40’. 


The format of the $SIT macro instruction is: 
{Name] $SIT} [10B-name] [,TYPE-DEC/BIN/TU/TOD}] 
LITYPE-REAL/WAIT/TASK] 


/OB-name specifies the name of the timer |OB generated by 
the $TIOB macro instruction. If this operand is omitted, 
the address of the IOB is assumed to be in register 2. 





TYPE-DEC/BIN/TU/TOD specifies the format of the time 
interval in the 1|OB. You must establish the time interval 
in bytes 2-7 of the IOB before issuing the $SIT inacro in: 
struction. The valid time interval formats are: 


e@ DEC: The time interval is the amount of time in decimal 
that is to elapse before the timer interrupt. The time 
interval is a six-byte decimal number specifying hours, 
minutes, and seconds (HHMMSS). 


@ BIN: The time interval is a 32-bit binary number speci- 
fying the number of seconds that are to elapse before the 
timer interrupt. The binary value must be right-justified 
in bytes 4-7 of the !OB field. 


@ TU: The time interval is a 32-bit binary number speci- 
fying the number of timer units that are to elapse before 
the timer interrupt. One timer unit is 3.33 milliseconds. 
The binary value must be right-justified in bytes 4-7 of 
the 1OB field. 


@ TOD: The time interval is the actual time of day when 
the timer interrupt is to occur. The time is a six-byte 
decimal number specifying the hour, minute and second 


(HIHMMSS). 


if this operand is omitted, DEC is assumed. 
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ITYPE-REAL/WAIT/TASK specifies the type of interval 
to be timed. The types of time intervals are: 


@ REAL: The timer decrements the time interval continu- 
ously for all types of processing. 


@ WAIT: The program issuing the $SIT macro instruction 
is placed in a wait state for the specified time interval. 
When the time has expired, control returns to the instruc- 
tion following the $S1T macro instruction. 


@ TASK: The timer decrements the time interval only 
while the task issuing the $SIT macro instruction is run- 
ning. 


If this operand is omitted, REAL is assumed. 


Return Time and Date ($TOD) 


This macro instruction returns the time of day and the 
system date to the program. The time of day is returned in 
bytes 2-7 of the timer 1OB, the system date in the next six 
bytes. DATE-Y must be specified in the $TIOB macro 
instruction if the $TOD macro instruction is used. 


The format of the $TOD macro instruction is: 


[Name] {10B-name] [,REF-Y/N] [,TYPE-DEC/BIN/TU] 


/OB-name specifies the name of the timer IOB generated 
by the $TIOB macro instruction. If this operand is omitted 
the address of the IOB is assumed to be in register 2. 


’ 


REF-Y/N specifies whether the macro instruction is being 
issued from the transient area or a program partition. Y 
(yes) indicates the macro instruction is issued by a transient 
that must be refreshed; N (no) indicates it is issued from a 
program partition. If this operand is omitted, N (no) is 
assumed, 
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TYPE-DEC/B8IN/TU specifies how the time is to be returned 
in the timer IOB. The valid formats are: 


@ DEC: The time returned is a six-byte decimal number 
indicating the time in hours, minutes and seconds 
(HHMMSS). 


@ BIN: The time returned is a 32-bit binary number indi- 
cating the time in seconds. The binary number is right- 
justified in bytes 4-7 of the IOB field. 


@ TU: The time returned is a 32-bit binary number indicat- 
ing the time in timer units. One timer unit is 3.33 milli- 
seconds. The binary number is right-justified in bytes 
4-7 of the IOB field. 


If this operand is omitted, DEC is assumed. 


Return Interval Time (SRIT) 


This macro instruction returns the remaining amount of 
time in a time interval or cancels an unexpired time interval. 
The remaining time is returned in bytes 2-7 of the timer 

[OB established by the $TIOB macro instruction. The time 
interval must have been set by the $SIT macro instruction 
and is returned in the format specified in that macro instruc- 
tion. 


The format of the $RIT macro instruction is: 


[Name] [IOB-name] [,CANCEL-Y/N} 


/OB-name specifies the name of the timer 1OB generated by 
the $TIOB macro instruction. If this operand is omitted, 
the address of the 1OB is assumed to be in register 2. 


CANCEL-Y/N specifies whether the remaining time in the 
interval is to be cancelled. If this operand is omitted, N (no) 
is assumed. 

End-of-Job (SEQOJ) 

The $EOJ macro instruction generates the linkage required 
to execute the end of job routine. The option to perform 


an immediate cancel or a controlled cancel is provided. 


The format of the $EOJ macro instruction is: 


[Name] [CANCEL-NORMAL/IMMED/CONTRL] 


CANCEL-NORMAL/IMMED/CONTRL specifies the 
action that the system should take as it terminates the 
program. If this operand is omitted or if NORMAL is 
specified and the system is in HALT mode, an end of job 
step message is issued and job processing terminates in the 
partition; if NOHALT mode is in effect, no message is 
issued and job processing continues. 


If IMMED is specified, the disposition of files depends upon 
the function being performed: 


® New files being created will not be retained 

®@ Old files being deleted will be retained 

© Old files being added to will not reflect the additions 

@ Old files being updated will reflect the updates made 
prior to the point at which this $EOJ macro instruction 


was executed 


® Add files (except for consecutive) will reflect additions 
if file sharing (5704-SC2 only). 


If CONTRL is specified, the files being used by your pro- 
gram reflect all activity which took place up to the point 
the $EOJ macro instruction was executed. 
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If your program specifies CANCEL-IMMED or CANCEL- 
CONTRL and it is a step of a job or a procedure ina 
chained procedure, all remaining steps in the job or ail 
remaining procedures in the chained procedure are cancelled. 
Also, EJ or ES is displayed regardless of the status of the 
system halt mode, and job processing in that partition 
terminates. 


If either CANCEL-IMMED or CANCEL CONTREL is speci- 
fied, the input stream is flushed in the following manner: 


@ \f you are executing in job mode on a system on which 
input spooling is active, job processing in the partition 
resumes with the next job on the job input queue. 


@ if you are executing in job mode on a system on which 
input spooling is not active, the job stream in the system 
reader is flushed until a JOB statement or a slash period 
(/.) statement is encountered. 


@ if you are executing in step mode, the input stream will 
be flushed until a JOB, LOAD, CALL, slash period (/.) 


or slash ampersand (/&) statement is encountered. 
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INPUT/OUTPUT SUPPORT MACROS 


The input/output support macro instructions provide access 
to devices without requiring that you write exterisive rou- 
tines to perform each function. The input/output support 
macro instructions are divided into eight groups: 


1. General macro instructions are usec with a:. deve 
types. The following macros are in tris gros... 


$ALOC 
oe 
$CHK 
$CLOS 
$COMN 
$DTFO 
SOPEN 


Teleprocessing oniy 


2. Card macro instructions support card devices, The 
following macros are in this group: 


$DTFC 
$GPC 

$SGETC 
SPUTC 


3. Printer macro instructions suppert printer aewices. 
The following macros are in this group. 


$DTFP 
$PUTP 


4. Disk macro instructions provide suuport anc inkage 
to disk data management. The toilowing niacros are 
in this group: 


$DTFD 
$GETD 
$l10BD 
$SIOED 
$PUTD 
$RDD 
$WAIT 
$WRTD 
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5. 


8. 


Tape macro instructions provide support and linkage 
f 

to tape data management. The following macros are 

in this group: 


SCTLT 
SDTFT 
SGETT 
SPUTT 
SROT 
SWRTT 
SWTT 


Device independent macro instructions provide sup- 
port and linkage to device independent data manage- 
ment. The following macros are in this group: 


SDTFI 
SGETI 
SPUT! 


CRT rnacro instructions support CRT devices. The 
foiiowing Macros are in this group: 


SCOEP 
SDTFS 
SGETS 
SPFKT 
SPFKY 
SPGS 

SPUTS 


3741 macro instructions provide support and linkage 
to 3741 data management. The following macros 
are in this group: 


SDTFK 
SGETK 
SPUTK 


General 1/O Support 


The general {/O support macro instructions are used with 
both unit record, tape, and disk devices. The normal 
sequence for using these macro instructions is: 


$SALOC to allocate the device to your program 
partition. 


SOPEN to prepare the file or device for use. 
{/O operations and any processing required. 


SCLOS to prepare the file and/or device for job 
termination. 


Allocate Space (SALOC) 


The routines called by the $ALOC macro instruction allo- 
cate unit record input/output devices and space on disk and 
tape devices. These routines check to ensure that: 


@ The system supports the requested device. 


® The device requested is available to the requesting 
program. 


@ The LOCATION parameter of the OCL file statement 
is valid. 


@ The correct disk pack is mounted and space is available 
to the calling program. 


@® The number of disk, tape, and device independent 
DTFs in the calling program is limited as follows: 
— 5704-SC1—The limit is 40. 
~ 5704-SC2—The limit is 192 with at least a 10K 
Partition. The limit is 128 with only an 8K 
Partition. 


For 5704-SC2, not all 192 disk and tape DTFs may be 
allocated in a single call to allocate. The maximum 
number of tape and/or disk DTFs in a single chain is 
as follows: 

— If all are disk, the maximum is 165. 

— If all are tape, the maximum is 148. 

— For combinations of disk and tape, the maximum 
varies between 148 and 165. To determine whether 
or not the DTFs can be allocated ina single call to 
allocate, multiply the number of disk DTFs by 17 
and multiply the number of tape DTFs by 19. If 
the sum of the above two numbers is not greater 
than 2816, the DTFs may be allocated in a single 
call. 


If the DTFs cannot all be allocated ina single call, make 
two DTF chains and two cails to allocate. 


@ The correct tape input file is mounted, or the tape label 
is written on the output file, and that the tape is posi- 
tioned at the beginning of the file. 


An allocate request requires that pre-open DTFs be sup- 
plied as input to the routine. Fora description of DTFs, 
see Define the File for Card (SDTFC), Define the File for 
Disk (SDTFD), Define the File for Device Independent 
($DTFI), Define the File for Printer ($D TFP), Define the 
File for CRT (SDTFS), Define the File for Tape (SDTFT), 
and Define the File for 3741 (SDTFK). \Nhen the allocate 
request is for a disk, a tape device, or a device independent 
file, OCL file statements are also required. More than one 
DTF can be allocated at one time by chaining the DTFs. 
To chain DTFs, you must enter the address of the next 
DTF in the DTF you are building. The last DTF in a chain 
has X'FFFF’ entered in place of the address. If your 
Program operates as an interrupt handler, such as a binary 
synchronous communications program, all DTFs in the 
program should be chained together and allocated in one 
operation. When an error condition occurs, the allocate 
routine calls halt/syslog to display the proper halt code. 


Note that if you will need to use the data in register 2 ata 
later time, you should save the contents of that register 
before issuing the $ALOC macro instruction. 


The following output is produced when control is returned 
to your program. 


©@ The contents of register 1 are restored. 


© The format-1 labels and configuration record are up- 
dated. 


©@ For anon-disk or non-tape DTF, bit 1 in the rightmost 
byte of the attribute bytes of the post-open DTF is set 
on to indicate device allocation. 


© For a device independent DTF, the device code (dis- 
placement O in the DTF — $DFDEV) is altered to 
indicate the appropriate device. 


@ The address of the first DTF allocated is returned in 
register 2. 


Note: \f you are using telecommunications, $4LOC must 


not be issued while a telecommunications operation is in 
process. 
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The format of the $ALOC macro instruction is: 


{Name] | $ALOC } [DTF-address] 


DTF-address specifies the address of the high-order byte of 
the DTF being allocated. |f this operand is not entered, the 
address of the DTF is assumed to be in register 2. 


Prepare An !/O Device (SOPEN} 


This macro instruction prepares an input/output file for 
data transfer. The file to be prepared (opened) must pre- 
viously have been allocated by using the allocate macro 
instruction. Depending on the device, one or more of the 
following functions are performed for each file opened. 


@ The post-open DTF is formatted (see Figure 9). 


@ Pre-open DTF information is preserved in the format-1 
label as required. 


@ Input/output buffers, index buffers, and IOBs are 
formatted. 


®@® Buffers are initialized as required. 


@ Disk file share area is prepared as required (5704-SC2 
only). 


@ Cards are positioned at the wait station for card output 
files. 


@ The index area on disk for indexed files and the data 
area on disk for direct files are formatted as required. 


@ Diagnostics are performed to ensure that: 
~ The access method and the file organization are 
compatible. 
— The volume and file are mounted on the correct disk 
or tape drive. 
— Share attributes are checked for disk files (5704-SC2 
only). 


Note: More than one DTF can be opened at one time by 
chaining the DTFs. To chain DTFs, you must enter the 
address of the next DTF in the DTF you are building. 

The last DTF in a chain has X‘FFFF’ entered in place of 
the address. See SOTFC, SDTFD, SDTFI, $DTFP, $DTFS, 
$DTFT, and $DTFK. 
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Pre-Open Conditions Post-Open Conditions 


. Unformatted DTFs are . Formatted DTFs are 
present for output created. 
files. 


. I/O buffers, 1OBs, and 


. The 1/O buffer is in the various work areas are 
unformatted mode. formatted. 


. Abit is set on in the 
DTF attribute bytes to 
indicate an opened file. 





Figure 9. Comparison of Pre-Open and Post-Open DTFs and 
Data Areas 


Input: The pre-open DTF and format-1 label are input to 
the open routine. Before the open macro instruction is 
issued, you must be sure to have the device allocated by 
previously issuing the allocate macro instruction. Also, if 
you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $OPEN macro instruction. You must also consider the 
following in preparing the DTF: 


@ The disk access method must be compatible with the 
disk file organization of the file being opened. 


@ The access method must be compatible with the access 
method of the same file opened in the other program 


level or for an inquiry program (see Ro//out). 


@ The record length, block length, and key length must be 
specified correctly. 


@ The file must have share specified if it is to be shared 


for disk files (5704-SC2 only). 


Output: The open routine returns control to your program 
when the requested file has been opened. The following 
output is produced: 

@ The contents of register 1 are restored. 


@ The format-1 labels are updated. 


@ Bit 7 in the rightmost attribute byte in the post-open 
DTF is set on to indicate the file has been opened. 


@ The device code (displacement 0 in the DIF — $DFDEV) 
is altered to indicate the unit on which the disk or tape 


file resides. 


@ The buffers are initialized. 





@ The address of the last DTF Opened is returned in 
register 2. 


@ The file share area is updated for disk files with share 
specified (5704-SC2 only). 


The format of the $OPEN macro instruction is: 


[Name] ] SOPEN | [DTF-address] 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file to be opened, If this operand is not 
entered, it is assumed that the address is in register 2, 


Note: Any files opened during a job should be closed 
before the job ends ($CLOS macro). For 5704-SC2 only, 
any open files will be closed during EOJ processing (nor- 
mal or abnormal). Therefore, DTFs must be available at 
this time. Any disk files opened using file sharing must 
be closed to perform required actions on the file share 
area. 


Generate a Checklist ($CKL ) 


This macro instruction creates an entry for a checklist. It 
does not generate executable code. A checklist identifies 
DTFs to be checked for 1/O completion, or determines 
whether the PF9 key has been pressed. Two kinds of DTFs 
can be identified in the checklist: 


® Binary Synchronous Communications (BSC) DTFs 


@ Dummy DTFs (15-byte DTFs used to check for the PF9 
key) 


All the checklist entries that are to be tested by the same 
$CHK macro instruction must be issued consecutively. 

The same DTF may be in the list more than once. The 
checklist entries that are generated are contiguous in main 
storage. You can then issue the $CHK macro instruction to 
test the entire list, by specifying the first entry in the list; 
or kegin testing anywhere in the list, by specifying the 

label of one of the later entries. 


Note: The address you specify in the $CHK macro instruc- 
tion identifies the beginning of the check operation. Any 
entries occurring earlier in the list are ignored in that 
operation. 


For a description of the checklist entries, see Figure 10. 


Disp _| Field Description 


0 Flag byte: 


X‘80’—Skip this entry 

X‘40'—Request key (PF Key 9) should be checked 

X‘20'—This is the last entry in the checklist 

X'10'—Return contro! to the user if no 1/O com- 
pletion is found {significant only in the 


first entry of a checklist) 
X‘08’—Code destroyed 
X'04’—Program function key not available 


Address of the DTF for this entry 





Figure 10. Checklist Format 


For a description of BSC, see /BM System/3 Multiline/ 
Multipoint Binary Synchronous Communications Reference 
Manual, GC21-7573. 


The format of the $CKL macro instruction is: 
[Name] | $CKL DTF-address[,SKIP-Y/N] .REQK-Y/N] 
LRTN-Y/N] [,LAST-Y/N] 


DTF-address specifies the symbolic address of the first byte 
of the DTF for which this entry is being created. A dummy 
DTF, 15 bytes in length, is required to check if the PF9 key 
was pressed. Displacement X‘00' in this DTF should con- 
tain a X‘10’ and a completion code will be returned at dis- 
placement X‘OE’. 





SKIP-Y/N specifies whether this entry should be skipped 

when the checklist is scanned, If this operand is omitted, 
N (no) is assumed. If Y is specified, you must update the 
checklist entry before you can check the DTF specified in 
this macro instruction. You can access the skip indicator 
in the entry by using the name specified on the macro in- 
struction. 


REQK-Y/N specifies whether the check routine (see index 
entry $8CHK macro instruction) should check if the PF9 

key has been pressed. Whenever you want the check rou- 
tine to check for a PF9 request, you must include a dummy 
DTF in the checklist and specify REQK-Y for that entry. 
REQK-Y is ignored if it is specified for a DTF that is not 

a dummy PF9 DTF (a device code of X‘10’ in the first 

byte of a DTF denotes a dummy PF9 DTF). ff the operator 
pressed the PF9 key, a completion code of X’50’ is posted 
at displacement X’OE’ of the dummy DTE. 
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RTN-Y/N specifies whether you want control returned to 
your program even if no 1/O operation is complete. This 
operand is valid only for the first entry in the check list. If 
this operand is not entered, N (no) is assumed. 


LAST-Y/N specifies whether this is the last entry in the 
checklist. LAST-Y (yes) must be specified for the last 
entry. If this operand is omitted, N (no) is assumed. 


Check for 1/0 Completion ($CHK) 


This macro instruction generates the linkage required to use 
the check routine. You must issue the $CHK macro instruc- 
tion for each BSC get, put, read, write, or online test 
request. For a description of BSC macro instructions, see 
IBM System/3 Multiline/Multipoint Binary Synchronous 
Communications Reference Manual, GC21-7573. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $CHK macro instruction. 


Check Routine Operation 


Note: When using this macro, the user program must 
equate $PARM to 2. 


The check routine tests for completion of an 1/O operation 
by examining the DTFs identified in the checklist — see 
Generate a Checklist (8CKL). \f an 1/O operation is com- 
plete, the completion code is set in the DTF, and the ad- 
dress of the DTF is returned in register 2 to the calling 
program. No subsequent DTFs in the list are tested. 


When no I/O completion is found by the end of the check- 
list, control is returned to your program with the address 
of the last DTF in the list register 2 if: 


Each entry in the list is inactive, closed, or has the skip 
indicator on (a completion code of X‘57’). 


RTN-Y was specified in the $CKL macro instruction 
that created the first entry in the checklist (a comple- 


tion code of X’56’). 


The format of the $CHK macro instruction is: 


$CHK {CKL-address] | 
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CK L-address specifies the symbolic address of the first entry 
in the checklist. You can also begin at a subsequent point 
in the checklist by specifying the symbolic address of a 

later entry. If this operand is omitted, the address is 
assumed to be in register 2. 


Note: The address you specify identifies the beginning of 
the check operation. Any entries occurring earlier in the 
list are ignored in that operation. 


Prepare a Device for Termination (SCLOS) 


The close macro instruction prepares a device for job termi- 
nation. The routine returns post-open DTFs to their pre- 
open state and updates file labels to reflect the current file 
status. For devices other than disk or tape, only the entries 
related to the requested functions are restored. {f you will 
need to use the data in register 2 at a later time, you 
should save the contents of that register before issuing the 
$CLOS macro instruction. 


Input to the close routine consists of the post-open DTF 
and the format-1 labels. The allocate and open macro in- 
structions must have previously been issued. 


Output created by $CLOS is returned to your program 
when control is returned. The output consists of: 

@ The contents of register 1 restored. 

@ The post-open DTFs reinitialized to the pre-open state. 


@ Any pending operations for unit record devices 
performed. 


@ The format-1 label for disk updated to indicate current 
file status. 


@ The buffer contents scheduled for disk or tape output 
and disk update operations written. 


@ The data and index written to disk, and an indicator set 
if key sorting is required at end-of-job for output files 
and file additions. 


@ Tape trailer labels read or written. 


@ The file share area is cleared or updated for the disk 
file specified as share. 


Note: More than one DTF can be closed at one time by 
chaining the DTFs. To chain DTFs, each DTF to be closed 
must contain the address of the next DTF in the chain. The 
last DTF in a chain has X‘FFFF’ entered in place of the 
address. 








The format of the $CLOS macro instruction is: 
[Namel | $CLOS | [DTF-addressi | 


DTF-address specifies the address of the te ttmest ayte af 
the DTF to be closed. |f this operand is ror entered the 
address is assumed to be in register 2. 


Generate DTF Offsets (SDTFO}) 


This macro defines the DTF labels, offsets 
and field lengths for ali devices and access methe : 
ed for the Model 15. To avoid duplicate iaheis, ths maces 
instruction should be used only once in each program: you 





held contents, 





should also set the operands to indicate any devices you 
plan to use in the program, 






$DTFO 





[Name] 





[DISK-Y/Ni {,TAPE-Y i i 
[MFCU YUN] DMECA. ¥ N D3f4ap yor i 
[,D2501-Y/NJ [02442 V/N) :.51493 YN: 
[,03284-Y/NJ [,CRT-Y/N} LALL-Y/N! 
(FIELD. V eM! 















a 


DISK-Y/N specifies whether iabels are te ne qeneratert ts 
disk devices. If this operand is not entered. % inosts 
assumed. 


TAPE-Y/N specifies whether labels are te ne qenerctont for a 
tape device. If this operand is net erterer: red 





assumed. 


IND-Y/N specifies whether lahels are te ne sen Gata tee an 
independent device. tf this operand ig aot orterpe: BE fac. 
is assumed. 

MFCU-Y/N specifies whether labels are t.. be generated fer 


the MFCU. If this operand is net entered, N ino) is assumed. 
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MFCM Y-~-% specifies whether labels are to be generated for 
the MFCM. !f this operand is not specified, N (no) is 
assumed. 


D3741-¥/N specifies whether labels are to be generated for 
the 3741. If this operand is not specified, N(no) is assumed. 


D250/. + % specifies whether labels are to be generated for 
the 256° /f this cperand is not entered, N (no) is assumed. 


D1442.Y-N specifies whether labels are to be generated for 
the 1442. 'f this operand 1s not entered, N (no) is assumed. 


D1403 ¥ % specities whether labels are to be generated for 
the 1403. Jf this operand is not entered, N (no) is assumed. 


03284.» % specifies whether labels are to be generated for 
the 3254. !f this operand is not entered, N (no) is assumed. 


CRT-Y "i :oecifies whether labels are to be generated for 
the CRT. :* this operand is not entered, N (no) is assumed. 


ALL-Y/’N specifies whether labels are to be generated for alt 
devices suioparted. If this operand is not entered, N (no) is 
assumed 


FIELD ¥.N specifies whether to generate the labels which 
define the contents for a DTF field. If this operand is not 


specifies: Y {ves! 1s assumed. 


COMMON Equates (SCOMN) 


This maces -ostructian generates equates for various fabels 
and vaiics., such as reaister equates, which may be used in 


the program. This macro instruction is not required. 


The formai of the SCOMN macro instruction is: 
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Card Device Support 


This section describes the macro instructions that support 
card devices. The following functions are provided: 


® Build a pre-open DTF for card device and assign its off- 
sets. 


© Build the interface required to read/punch/print records 
using a card device. 


The DTF provides information to the card device data man- 


agement routines that perform input/output operations. 


Define the File for Card (SDTFC) 
The DTF provides information needed to allocate, open, 
and access a card device. This macro instruction generates 


the code that builds a card DTF. 


The format of the $DTFC macro instruction is: 


[Name] | SDTFC | 1OBA-address, NIOB-number 
[,DEV code] 
[,UP-mask] [,CHN-address] 
[,RCAD-address] [,OPC-code] 
[,DEFER-Y/N] [L,.CARDI-Y/N] 
{,PRINT4-Y/N] {,FEED-Y/N] 


[,STACKR-number] [,READA-address] 
[,PUNCHA-address] [,PRINTA-address] 
[,READL-number] [,PUNCHL-number] 
[,PRINTL-number] [,PRHEAD-mask] 
LALIGN-Y/N] 


!OBA-adadress is a required operand specifying the address 
of the leftmost byte of the first IOB. The area identified 
by this operand must be large enough to contain one [OB 
for single buffering or two IOBs for double buffering 
(specified via the operand NIOB-2). The sizes for each 
card IOB are: 


2501 — 25 bytes 
MFCU — 29 bytes 
1442 — 29 bytes 
MFCM — 31 bytes 
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NIOB-number is a required operand specifying the number 
of IOBs associated with this DTF. This entry must have a 
value of 1 or 2. 


DEV -code specifies the card device desired. The possible 
values for code are MFCU1, MFCU2, MFCM1, MFCM2, 
1442, and 2501. If this operand is omitted, MFCU1 is 
assumed. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all Zeroes or not used, the file will be unconditionally 
opened. 


Note: Information on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the 
IBM System/3 Model 15 System Control! Programming 
Concepts and Reference Manual (tor Program Number 
5704-SC2), GC21-5162. 


CHN-address indicates the address of the next DTF in the 
chain of DTFs. {f there is no DTF chain or if this is the 
last DTF in the chain, the operand should be omitted 
(X'FFFF’ is assunied). 


RCAD.-address specifies the leftmost byte of the logical 
record for an output operation. If this operand is not 
entered, a value of X‘Q000' is assumed: this value must be 
updated before an output operation is performed. If this 
operand 1s specified for an input operation, the value speci- 
fied will not be used, and this operand will be modified by 
the card data management module to contain the address of 
the card that was read. 


OPC-cade detines the operation code for the DTF. A list 
of the possible codes and their meanings are: 


Code Meaning 

RD Read 

PU Punch 

PR Print 

PP Punch and print Not allowed for 
RPU Read and punch MFECM1 

RPR Read and print or 

RPP Read, punch, and print } MFCM2 


if this operand is not specified, the operation code for a 
feed is set. 


DEFER-Y/N is used only with output Operations to the 
MFCM and MFCU. This operand enables you to print one 
record on a card and punch a different record in the same 
card. The $SDTFC, $PUTC, and $GPC macro instructions 
can be used to specity this process. For $GPC or $PUTC, 
you must first issue that macro instruction for either a 
print or a punch with DEFER-Y. You then modify the 
logical record as needed to a different format and issue that 
macro instruction for the remaining operation with 
DEFER-N. Both operations are then performed. If this 
operand is not specified, N (no) is assumed, 


CARDI-Y/N specifies whether or not to perform a read 
card image operation on the 1442 or 2501. If N (no) is . 
specified or if this operand is omitted, a card image read is 
not performed. 


PRINT4-Y/N specifies whether to print three or four tiers 

for a print request from the MFCU. Y (yes) indicates that 
four tiers should be printed, :f this operand is omitted or if 
N (no) is specified, three tiers are printed. 


FEED-Y/N specifies whether or not to perform a feed oper- 
ation after a 1442 punch operation. if Y (yes) is specified 
or if this operand is omitted, a feed is performed after the 
punch operation. 


STACKR-number specifies the stacker to be used for this 
card operation. This operand is not used with the 2501. If 
this operand is not specified, the byte containing the 
stacker number will be set to X‘00’. 


Note: |f this operand is zero the following occurs: stacker 
one is used if the card originated in hopper 1; the highest 


number stacker is used if the card originated in hopper 2. 


READA-address specifies the address (at a 128-byte boun- 
dary) of the buffer used for read operations. If double buf- 
fering is used, both buffers must be on 128-byte bound- 
aries, and the two buffers must be contiguous in main stor- 
age. You must specify this operand if you plan to use this 
DTF for a read operation. 


PUNCHA.-address specifies the address (at a 128-byte boun- 
dary) of the buffer used for punch operations on the 1442, 
MFCU, or MFCM. If double buffering is used, both buffers 
must be on 128-byte boundaries, and the two buffers must 
be contiguous in storage. You must specify this operand 

if you plan to use this DTF for a punch operation. 


PRINTA-address specifies the address (at a 256-byte boun- 
dary) of the buffer used for print operations on the MECM 
or the MFCU. For the MFCM, the buffer size must be 64 
bytes times the highest print head used. If double buffering 
is used, both print buffers must be contiquous in main stor- 
age. For the MFCU, the buffer size must be 128 bytes for 
single buffering and 256 bytes for double buffering. If two 
DTFs are being used for printing from both hoppers of the 
MFCU, the operation must be single buffered and the DTFs 
must use the same 256-byte print area. You must specify 
this operand if you plan to use this DTF for a print operation. 


READL-number specifies the number of card columns to 
read. This operand should be used with the MFCM or 2501 
only. If this operand is not specified, the maximum value 
(80) is assumed. 


PUNCHL-number specifies the number of card colurnns to 
punch. This operand should be used with the MFCM or 
1442 only. If this operand is not specified, the maximum 
value (80) is assumed. 
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PRINTL-number specifies the number of columns to print 
per head on the MFCM. If this operand is not specified, the 
maximum value (64) is assumed. 


PRHEAD-mask defines the print heads selected for the 
MFCM. The mask must be specified as an eight-bit field. 
If this operand is omitted, the current setting of the print 
head selection byte in the DTF is not modified. The fo}- 
towing table shows the meaning of each bit. 


Bit Meaning 

Oand1=0 Unused, must be zero 

2= Select print head six 

3=1 Select print head five 

4= Select print head four 
= 1 Select print head three 
=1 Select print head two 
=4 Select print head one 


ALIGN-Y/N specifies whether to print in a special format 
on the MFCM. If Y (yes) is specified, the first 64 charac- 
ters are printed with print head 1 and the next 16 charac- 
ters are printed right-justified with print head 2. If N (no) 
is specified or if this operand is not entered, printing occurs 
in the normal manner. 


Construct a Card Get Interface (SGETC) 


The $GETC macro instruction generates the interface re- 
quired to communicate with card data management when a 
record is being read from a card device. To use this instruc- 
tion, you must construct a card DTF for the file and use 
the $DTFO macro instruction to establish the offsets in 
the DTF. If you will need to use the data in register 2 at a 
later time, you should save the contents of that register be- 
fore issuing the $GETC instruction. You must also provide 
the labels for the necessary data management routines, via 
EXTRN statements in your program. The names of the 
data management routines for each device are: 


Module Name Device 
$$MFRD MFCU 
$$MMRD MFCM 
$SARFF 1442 
$$ARRD 2501 
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The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If 
the ERR or EOF operand is specified, the generated code 
tests the completion code returned by data management 
and branches to your routine. 


The format of the $GETC macro instruction is: 


[DEV-code} [,DTF-address] [,EOF-address] 
[,ERR-address] [,OPC-Y/N] 


{,READL-number} {,CARDI-Y/N] 
{,STACKR-number] 





DEV-code specifies the appropriate device. One of the 
following codes must be used: MFCU, MFCM, 1442, or 
2501. If this operand is not specified, default is made to 
MFCU. 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


EOF-address specifies the address in your program that re- 
ceives control when the end-of-file is detected. If this oper- 
and is not supplied, no code is generated to check for the 
end-of-file condition. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


Note: |If ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 


OPC-Y/N indicates whether or not the read operation code 
should be altered in the DTF. If Y (yes) is specified, the 
read/punch/print bit in the operation code is set to indicate 
aread. If N (no) is specified or if this operand is omitted, 
read/punch/print bit in the operation code is not modified. 


READL-number specifies the number of columns to read 
from the MFCM or 2501. If this operand is not specified, 
the DTF remains unchanged. 


CAR! © /N specities whether to perform a read card image 
operation on the 1442 or 2501. If Y (yes) is specified, the 
cald imaye read bit in the operation code is set on. If N 
(110) 1s specified, the card image bit in the operation code is 
seLoth. Hf this operand is omitted, the status of the card 
iaage read bit in the operation code is not modified. 


STACK H ribet specifies the stacker to be used for hold- 
iy the cards after the read operation. This operand is not 
used with the 2501. tf this operand is not given, the value 
ui the DTF is not changed. 


Culisliuct a Card Put Interface {$PUTC) 


Viis macro instruction gerierates the interface needed to 
communicate with card data management when punching 
and/or printing a card file. You must provide a DTF for 
ihe tile and use the SDTFO macro instruction to establish 
the offsets in the DTF. You must also provide, through 
EXTRIN staternents in your program, the labels of the card 
data management modules necessary to perform the output 
operation. The names of the data management routines for 
each device are: 


Modtle Name Device 
SSMPEPP MFCU 
$SMMPP MFCM 
SSARFF 1442 


If you need to use the data in register 2 at a later time, you 
should save the contents of that register before issuing the 
SPUTC instruction. 


[he code generated by this macro instruction gives control 
to the data managernent routine. The routine completes 
execution and returns control to the generated code. If the 
ERR operand is specified, the generated code checks the 


completion code for errors and branches to your error rou- 
tine if errors occurred. 


The format ot the $PUTC macro instruction is: 





[Name] ] $PUTC | [DEV-code] [,DTF-address} [,OPC-code] 
[,DEFER-Y/N] [,PRINT4-Y/N) 
[,FEED-Y/N] [,STACKR-number |} 
{[,PUNCHL-number] [,PRINTL-number] 


L.PRHEAD-mask] [,ERR-address] 







DEV-code specifies the appropriate device. One of the fol- 
lowing codes must be used: MFCU, MFCM, or 1442. If 
this operand is not specified, default is made to MFCU. 


DTF-adidress specities the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assumed to be in register 2. 


OPC-code specifies the operation code to be used, If this 
operand is not specified, the status of the print/punch bits 
in the operation code is not changed. Valid codes are as 
follows: 


Code Meaning 

PU Punch 

PR Print 

PP Print and punch (This code is not allowed 


for MFCM.) 


DEFER-Y/N specifies whether the print and/ac punch oper- 
ation should be deferred. It Y (yes) is specified. the defer 
operation bit in the operation code ys scr on, if N {ne} is 
specified, the defer opcrai.on bit in the oneration cod: 1% 
set off. lf this operand is ot specified, t-e status of coe 
defer bit is not changed. 


PRINT4-Y/N specifies whether to print on four tiers of the 
MFCU card. If Y (yes) is specified, the fourth tier print bit 
in the operation code is set on; if N (no) is specified, the 
fourth tier print bit is set oft. If this operand is ornitted, 
the status of the fourth tier print bit in the operation code 
is not changed. 


FEED-Y/N specifies whether to perform a feed operation 
following the 1442 punch operation. Y (yes) indicates that 
a feed should occur after the punch; if N (no) is entered, a 
feed is not performed after the punch operation. !f this 
operand is omitted, the status of the feed/iio feed bit in the 
DTF is not changed. 


STACKR-number specifies the stacker to be used for this 
operation. If this operand is omitted, the value of the 
stacker-select byte in the DTF is not changed. 


PUNCHL-number specifies the number of columns to punch. 
If this operand ts omitted, the value im the punch-length 
byte is not changed. This operand shouid be used with the 
MFCM or 1442 only. 


PRINTL-number indicates the number of columns to be 
printed by each head on the MFCM. If this operand is 
omitted, the value in the print-length byte is not changed. 
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PRHEAD-mask defines the MFCM print heads selected. 
The mask must be specified as an eight bit field. If this 
operand is omitted, the current setting of the print head 
selection byte in the DTF is not modified. The following 
chart shows the meaning of each bit: 


Bit Meaning 


® 
5 


It 
see]. 242456 


1=0 Unused, must be zero 
Select print head six 
Select print head five 
Select print head four 
Select print head three 
Select print head two 
Select print head one 


NOOR WM © 
I 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent 1/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code, and you should check the return code in 
your program to determine the outcome of the operation. 


Construct an Interface for Reading, Punching, and Printing 
Cards (SGPC) 


The $GPC macro instruction generates the interface required 
to communicate with card data management when a record 
is being read, punched, and/or printed on a card device. To 
use this macro instruction, you must construct a card DTF 
for the file and use the $DTFO macro instruction to estab- 
lish the offsets in the DTF. If you will need to use the data 
in register 2 at a later time, you should save the contents of 
that register before issuing the $GPC instruction. You must 
also provide labels for the necessary data management rout- 
ines via EXTRN statements in your program. The name of 
the data management routine for each device is: 


Module Name Device 
$$MFFF MFCU 
$$MMFEF MFCM 
$$ARFF 1442 


The code generated by this macro instruction gives control 
to the data management routine: the routine completes 
execution and returns control to the generated code. If the 
ERR or EOF operand is specified, the generated code tests 
the completion code returned by data management and 
branches to your routine. 
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The format of the $GPC macro instruction is: 
[Name] | $GPC [DEV-code] [,DTF-address} [,OPC-code] 
[,DEFER-Y/N] [,CARDI-Y/N] 
[,PRINT4-Y/N] [,FEED-Y/N] 


{,STACKR-number] [,READL-number] 
[,PUNCHL-number] [,PRINTL-number] 
{,PRHEAD-mask] [,EOF-address] 
[,ERR-address] 





DEV-code specifies the card device desired. The possible 
values for this code are: MFCU, MFCM, and 1442. If this 
operand is not specified, MFCU is the default value. 


DTF-address specifies the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assumed to be in register 2. 


OPC-code specifies the operation code to be used. Valid 
codes and their meanings are: 


Code Meaning 

RD Read only 

PU Punch only 

PR Print only 

PP Punch and print 

RPU Read and punch Not allowed 
RPR Read and print for MFCM 
RPP Read, punch, and print 


If this operand is not specified, the status of the read/ 
punch/print bits in the operation code is not changed. 


DEFER-Y/N specifies whether to defer the punch and/or 
print request. If N (no) is specified the request is not de- 
ferred; if this operand is not specified the status of the 
defer bit in the DTF is not changed. 


CARDI-Y/N specifies whether to perform a read card image 
operation on the 1442 or 2501. !f N (no) is specified or if 
this operand is omitted, a card-image read is not performed. 


PRINT4-Y/N specifies whether to print three or four tiers 

for a print request from the MFCU. Y (yes) indicates that 
four tiers should be printed; if this operand is omitted or if 
N (no) is specified, three tiers are printed. 


FEED-Y/N specifies whether or not to perform a feed 
operation after a 1442 punch operation. If Y (yes) is 
specified or if this operand is omitted, a feed is performed 
after the punch operation. 


STACKR-number specifies the stacker to be used for this 
card operation. This operand is not used with the 2501. If 
this operand is not specified, the byte containing the stacker 
number is set to X‘00’. 


READL-number specifies the number of card columns to 
read. This operand should be used with the MFCM or 

2501 only. If this operand is not specified, the default value 
is 80. 


PUNCHL-number specifies the number of card columns to 
punch. This operand should be used with the MFCM or 


1442 only. If this operand is not specified, the default value 
is 80. 


PRINTL-number specifies the number of columns to print 
per head on the MFCM. If this operand is not specified, the 
default value is 64. 


PRHEAD-mask defines the print heads selected on the 
MFCM. The mask must be specified as an eight bit field. 
If this operand is omitted, the current setting of the print 
head selection byte in the DTF is not modified. The fol- 
lowing table shows the meaning of each bit: 


Bit Meaning 


1=0 Unused, must be zero 
Select print head six 
Select print head five 
Select print head four 
Select print head three 
Select print head two 
Select print head one 


EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 


operand is not supplied, no code is generated to check for 
the end-of-file condition. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent 1/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


Note: \f ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 


Printer Support 


This section describes the macro instructions that support 
the printers. The following functions are provided: 


@ Build a pre-open DTF for a printer and assign its offsets. 
The DTF provides information to printer data manage- 
ment routines that perform input/output operations. 


@ Build the interface needed to print data. 


Define the File for Printer (8SDTFP) 


The DTF provides information needed to allocate, open, 
and access a printer. This macro instruction generates the 
code that builds the printer DTF. 


The format of the $DTFP macro instruction is: 


[Name] | $DTFP 


RCAD-address,|OBA-address, J}OAA-address, 
OVFL-number,PAGE-number [,DEV-code] 
[,UP-mask] [HUC-Y/N] [,CHN-address] 


(,PRINT-Y/N] [,SKIPB-number] [SPACEB- 
number] {,SKIPA-number] [,SPACEA-number] 
[,RECL-number] 





RCAD-address is a required operand which gives the address 
of the leftmost byte of the logical record. 


/OBA-address is a required operand specifying the address 
of the leftmost byte of the I|OB. The IOB will be 50 bytes 
long. 


1OAA-address is a required operand which specifies the 
address of the leftmost byte of the I/O area. For the 1403, 
this address must define the |/O area as beginning on a 124- 
byte boundary. The length of the 1/O area must be: 

@ 132 bytes for the 1403 printer 


@ The record length +7 for the 3284 printer. 
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OVFL-number specifies the line number on the printer 
after which the overflow completion code will be returned. 
if this operand is not specified, default is made to 6 lines 
less than the number specified for the PAGE operand. 


PAGE-number specifies the number of lines to print per 
page. If this operand is not specified, default is made to the 
system value for the number of lines per page. 


DEV-code specifies the printer desired. The possible values 
for this code are 1403 and 3284. If this operand is not 
specified, 1403 is assumed. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. tf the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 


Note: \Intormation on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control! Programming Reference Manual for Pro- 
gram Number 5704-SC1, GC21-5077 and /BM System/3 
Model 15 System Control Programming Concepts and 
Reference Manual for Program Number 5704-SC2, GC21- 
5162, 


HUC-\’/N specifies whether to halt if an unprintable charac- 
ter is detected. If N (no) is specified or if this operand is 
omitted, no halt occurs. 


CHWN-address indicates the address of the next DTF in the 
chain of DTFs. If there isno DTF chain or if this is the 
last DTF in a chain, this operand should be omitted (a 
value of X’FFFF’ is assumed). 


PRINT-Y/N specifies whether to perform a print and a skip 
or space or only a skip or space. Default is N (no), mean- 
ing that a print is not performed. 


SKIPB-number specifies the line to skip to before the print 
operation. !f this operand is not entered, the default value 
is zero. 
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SPACEB-number specifies the number of lines (maximum 
of 3 lines) to space before the print operation. If this 
operand is not entered, the default value is zero. 


SKIPA -number specifies the line to be skipped to after the 
print operation. If this operand is not specified, the default 
value is zero. 


SPACEA-number specifies the number of lines to space (0, 
1, 2, or 3) after the print operation. If this operand is not 
specified, it defaults to a value of zero if DEV-1403 is speci- 
fied or to a value of one if DEV-3284 is specified. A space 
after of zero is not allowed for the 3284 printer, and, if 
zero is specified, the operand defaults to a space after of 
one. 


RECL-number specifies the length of the line to be printed. 
If this operand is omitted, default is 132 positions. 


Construct a Printer Put Interface ($PUTP) 


This macro instruction generates the interface needed to 
communicate with printer data management. You must 
provide a DTF for the file and use the $DTFO macro 
instruction to establish the offsets in the DTF. You must 
also provide, through an EXTRN statement in your pro- 
gram, the label $$LPRT, for the 1403, or $S$LPMP, for the 
3284. (These labels are for the printer data management 
module necessary to perform the printer output opera- 
tion.) 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $SPUTP macro instruction. 


The code generated by this macro instruction gives control 
to the data management routine. The routine completes 
execution and returns control to the generated code. If the 
ERR operand is specified, the generated code checks the 
completion code for errors and branches to your error 
routine if errors occurred. 


The format of the $PUTP macro instruction is: 


{DEV-code] [,DTF-address] [,PRINT-Y/N] 
{,SKIPB-number] [,SPACEB-number] 


[SKIPA-number] [,SPACEA-number] 
[,ERR-address] [,OVFL-address] 





DEV -code specifies the printer device desiied. The possible 
values for this code are 1403 and 3284. If this operand is 
not specified, 1403 is the default value. 


DTF-address specifies the address of the leftmost byte of 
the DTF for this file. If this operand is not entered, the 
address is assumed to be in register 2. 


PRINT-Y/N specifies whether to perfrom a print and a skip 
or space or only a skip or space. If this operand is not 
specified, the DTF remains unchanged. 


SKIPB-number specifies the line to skip to before the print 
operation. If this operand is not entered, the DTF remains 
unchanged. 


SPACEB-number specifies the number of lines to space be- 
fore the print operation. If this operand is not entered, the 
DTF remains unchanged. 


SK/IPA-number specifies the line to be skipped to after the 
print operation. If this operand is not entered, the DTF 
remains unchanged. 


SPACEA-number specifies the number of lines to space after 
the print operation. If this operand is not entered, the DTF 
remains unchanged. 


ERR-address supplies the address in your program where 
contro} is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code, and you should check the return code in 
your program to determine the outcome of the operation. 


OVFL-address specifies the address in your program that 
should receive control if page overflow occurs. 


Disk Device Support 


This section describes the macro instructions that support 
disk devices. The following functions are provided: 


@ Build a pre-open DTF for disk GET/PUT operations 
and assign its offsets. 


@ Build an input/output block (IOB) for disk read/write 
operations and assign its offsets. 


@ Build the interfaces required to get input records from a 
disk device via a get or a read. 


@ Build the interfaces required to put output records to a 
disk device via a put or a write. 


® Build the interface to wait for disk completion. 


The disk DTFs provide information to the disk data man- 
agement, and the disk |OBs provide information to the 
input/output supervisor routines that perform the input 
or output operations. These operations are provided 
through the disk support macro instructions. 


The IBM 3340 Direct Access Storage Facility attaches to 
System/3 Models 15B, 15C, and 15D. Also, the IBM 3344 
Direct Access Storage attaches to System/3 Model 15D. 


Certain areas on the 3340 and 3344 disks are treated as 
5444 disks. These areas, known as simulation areas, are 
used for program libraries and can also be used for data 
files. These areas cannot contain multivolume or indexed 
files. The remainder of the disk space, known as main 
data areas, can only be used for data files. 


Reference in this manua! to 5444, 5445, and 3340 are to 
be interpreted according to which disk storage device(s) 
is attached to the system. The following table should be 
used to determine the meaning of the reference: 


References to D3 and D4 Q-numbers in this manual may be 
replaced with D31 and D41 for 5704-SC2. 
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Page of GC21-7608-2 
Issued 28 March 1980 
By TNL: GN217-5700 


Model 15A Model 15B and 
Reference | Meaning 15C Meaning 


5444 5444 Disk Simulation 
Storage area on 
3340 


Mode! 15D 
Meaning 


Simulation 
area on 3340 
or 3344 










Drive 













5445 Disk 
Storage 


Main data 
area on 
3340 


Main data 
area on 3340 
or 3344 










Not 
applicable 









Main data 
area on 3340 


Main data 
area on 3340 
or 3344 





For Program Number 5704-SC2, there are certain restric- 
tions on where the DTFs and associated fields can be located 
relative to 40K (X‘E000’) in the user partition: 


@ DTFs must be tocated such that the entire DTF resides 
at an address less than 40K for batch disk files speci- 
fied as SHARE-YES and for CCP disk files. 


®@ For the following disk access methods where SHARE- 
YES is specified, the high add key and the high prime 
key areas (ADKEY parameter) must be located 
completely below 40K: 
— Indexed output add 
— Indexed random input and add 
— Indexed random input, update and add 


@ |f adisk file is specified with external buffers, then 


the following must be located completely below 
40K: 

— The DTFs 

— The index |OBs (IO parameter) 

~ The master track index (MSTX parameter) 


-- The space for the multivolume extent table (IO 
parameter, M, and M, definitions) 


Define the File for Disk (SDTFD) 


The DTF provides information needed to allocate, open, 
and access a file on the disk device. This macro instruction 
generates the code that builds the disk DTF. See Appendix 
B: Define the File Control Blocks for a description of the 
pre-open and post-open disk DTFs. 
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The format of the $DTFD macro instruction is: 


$DTFD | AC-code,RECL-number, NAME-filename, 
BLKL-number,!O-address 
[,DISK-5444/5445/3340) 
[,UP-mask] [,BUFNO-1/2] [,MVF-N/Y] 
[,LIM-N/Y] [,ORD-N/Y] [,BIN-N/Y] 
[,CHN-address] [,RCAD-address] 


[,ENT-number] [,MVFN-number] 

[,.KEYL-number] [,KEYD-number] 
[,KEYA-address} [,MVFT-address] 
[,MSTX-address] [,IBLKL-number] 
[,ADKEY-address] [,EOVK-address] 
L.SHR-Y/N]' [,EXTBUF-Y/N]! 





"These parameters are valid only for Program Number 5704-SC2. 


AC-code specifies the access method used for the file. This 
operand is required. The codes and their meanings are as 
follows: 


Code Access Method 

CA Consecutive add 

CG Consecutive get 

co Consecutive output 

CU Consecutive update 

DG Direct get 

DO Direct output 

DU Direct update 

IA indexed add 

lO Indexed output 

IS Indexed sequential get 

ISA Indexed sequential add 

ISL Indexed sequential input with limits 
ISU Indexed sequential update 

ISUA Indexed sequential update and add 
ISUL Indexed sequential input update with limits 
IR Indexed random get 

IRA Indexed random add 

IRU Indexed random update 

IRUA Indexed random update and add 


RECL-number specifies the decimal length of the logical 
record. This operand must be specified. 


NAME -file name specifies the name of the file. The name 
must be eight characters or less in length. This operand 
must be specified. 








BLKL-number specities the number of bytes in the putter. 


The minimum number can be determined as foliows, except 


for the access methods fisted on the following pages, for 
which the minimum number of bytes is 256: 


Hf the record length ts less than or vquai to 286 and 
evenly divisible :nto 256, the puffer length is 25€ 





@ If the record iength is greater than 256 arid a multiple 
of 256, the buffer iength is equa! to the record length. 


@ if tne record Jenath is net ev 


Ige 


not a muitiple of 256, the buffer fengitt 1s 





vesiole into 256 and 


tne mui tiole 


of 256 that is next higher than the rec. lenath plus 


255. 


If the record tength is an odd muitipie of 128, the ouffe 


shouid be the record length pius 128. 





Access Method 
Consecutive, Direct 


Indexed Output 


indexed Random Input, or 
Indexed Random tnaut and 
Update 


indexed Random input and 
Aad, or Indexed Random 
input, Update, and Add 


Indexed Add 
(without input) 


Indexed Sequential Input, 
or indexed Sequentiai 
Input and Update 


Indexed Sequential! 

Input and Add, or 
Indexed Sequential laput 
Update, and Add 


indexed Sequential /limits 
input, at indexed 
Seauuential/Limits input 
and Update 


SUnEEIE SEE 
| Furruta 


pe ein 





(BENG. + 30) tines BLIENO 


§ 2584 60) times 


PNOPS KE YL tar MVE 





{258 + 30) 





+My where 

My, 0 tor single voiume fies 

M, B4 * KEYL ior moult 
teatime fila OF a } 

M. t10 4 KEVYEL to ut 
Lourie piles $5704-SC 3: 





Hosingie wGrume files 









Me KEV EL for isu: 
vO! e files 
(BLKi + 30} + (968 + 3Q8 


+256 times IBL KL + 30 


PBLKS + 3M) 
IBLKL =» so 


+ 256 times 


2 times (BLK L + 30} 4 
2 times (256 times IBLKL 


+ 3h} 


Se 





| EXTBUF-Y _ 
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Note: These buffer lengths are minimum lengths. Larger 
iengths may be specified, but must be in multiples of 256. 


The following access methods can always operate in a mini- 





mum of a 26 


Consecutive output 
Consecutive add 


oyte buffer: 


Consecutive output multivolume 
Consecutive add muitivolume 


Consecutive input 


Consecutive input multivolume 


Indexed output 


indexed output multivolume 


iO-address provides the address of the leftmost byte of an 
area in main storage allocated to contain all buffers and 
!OBs tor the access method. This operand must be speci- 


fied 
tollowing chart: 


| (Space in 1/O area) 


SE tmes BUIFNS 


YA times BUFNO + KEYL 
Sar MVE 


72° My 
At. 6} for single volume files 
Me B4+ KEYL for multi- 
sohume files (5704-SC1) 
fA 1412 + K EYL for multt 
volume files (5704-SC2) 


where 


1443M 
Ms 9 far singte votume tiles 
Mo BO + KREYL for mutt 


yorum Files 


where 


108 


Nn 


744 


he amount of main storage required is shown in the 









Formula for External Buffers on 
Option Statement 

















BLKL times BUFNO 


BLKL + 256 times BUFNO 


BLKL +512 


2 times BLKL + 512 
+ (256 times IBLKL) 


BLKL + 512 + (256 times IBLKL}) 


BLKL + (256 times IBLKL) 


2 times BLKL + 2 times (256 
times IBLKL) 





BLKL + 256 + 256 (BLKL) 
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DISK-5444/5445/3340 specifies whether the disk device is 
the 5444 Disk Storage Drive, the 5445 Disk Storage, or the 
3340 Direct Access Storage Facility. If this operand is not 
specified, 5444 is assumed. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 


Note: Information on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control Programmming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the /BM 
System/3 Model 15 Control Programming Concepts and 
Reference Manual (for Program Number 5704-SC2), 
GC21-5162. 


BUFNO-1/2 allows you to specify either one or two buffers 
for the file. You can use two buffers only with consecutive 
access methods and indexed output. All consecutive access 
methods allow dual buffering except the consecutive up- 


date and consecutive update muitivolume. If this operand 
is omitted or if SHR-Y is specified, one buffer is assumed. 


MVF-N/Y specifies whether the access method is multi- 
volume. If this operand is omitted, N (no) is assumed. 


LIM-N/Y is specified only for indexed sequential get and 
indexed sequential update. It specifies whether the sequen- 
tial access is within limits. 1f this operand is not entered, 

N (no) is assumed. 


ORD-N/Y specifies whether an ordered load is to be used 
with the indexed output access method. This operand can 
be specified only with the indexed output access method. 
ORD-Y must be specified for indexed multivolume output 
access methods. If this operand is not entered, N (no) is 
assumed. 
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BIN-N/Y is specified only with the direct output, direct get, 
and direct update access methods. Y (yes) indicates direct 
binary relative record numbers; N (no) indicates direct deci- 
mal relative record numbers. If this operand is omitted, N 
is assumed. 


CHN-address specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and X'FFFF’ assumed. 


RCAD.-address specifies the address of the leftmost byte of 
the logical record. {f this operand is not entered, X‘0000’ 
is assumed. Depending on the disk access method being 
used for an input operation, either move mode or locate 
mode is used. If move mode is used, the record is provided 
at the address specified in the RCAD parameter. If locate 
mode is used, the address of the input record is contained 
at the displacement of $DFLRA in the DTF. 


The specified address plus the total length of the area 
must be less than logical X’EQO0’ for files that are being 
shared or for files that are being used for external buffers 
(5704-SC2 only). 


ENT-number specifies the number of entries in the master 
track index. This operand is specified only for indexed 
random or indexed add access methods. 


MVFN-number indicates the number of volumes for a 
multivolume direct access method. This operand must be 
specified for these access methods. 


KEY L-number specifies the length of the key field and 
must be used for all indexed access methods, but no others. 
The key field length can be no more than 29 bytes. 


KEYD-number is entered for all indexed access methods. 
It indicates the displacement into the record of the right- 
most byte of the key field. The displacement of the first 
byte in the record is zero, the second byte is one, and so on. 


KEY A-address specifies one of the following and is a 
required operand for these access methods: 


@ Main storage address of the leftmost byte of the key 
field for indexed random access methods. 


@ Main storage address of the leftmost byte of the relative 
record number field for direct access methods. 


@ Main storage address of the leftmost byte of the save 
area for current and last keys for indexed sequential add 
access methods. 


@ Main storage address of the leftmost byte of the save 
area for high and low keys for indexed sequential with 
limits access methods (LIM-Y). The specified address 
plus the total length of the area must be less than logical! 
X’'E000’ for files that are being shared or for files that are 
being used for external buffers (5704-SC2 only). 


You must allocate the main storage space for the fields. 
The amount of space required is: 


@ The number of bytes in the key field for indexed ran- 
dom access methods. 


®@ 23 bytes for direct access methods with decimal keys. 
The decimal key is located in the rightmost 15 bytes of 
the field. 


@ 8 bytes for direct access methods with binary keys. 
The binary key is located in the rightmost 3 bytes of 
the field. 


®@ Two times the key length for indexed sequential add or 
indexed sequential with limits access methods. The low 
key is located in the left half of the field; the high key in 
the right half. 


MVFT-address must be specified for all multivolume direct 
files, and only for the access methods used with these files. 
This operand specifies the address of the leftmost byte of 
the table of extents used for the access methods used with 
these files. You must allocate main storage space for the 


table. The number of bytes allocated must be equal to 
seven times the number of volumes in the file. With 


5704-SC2, if the multivolume file is to be shared, the 
number of bytes allocated must be ten times the number 
of volumes in the file. The specified address plus the total 
length of the area must be less than logical X‘EOOO’ for 
files that are being shared or for files that are being used 
for external buffers (5704-SC2 only). 
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MSTX-address specifies the address of the leftmost byte of 
the master track index in main storage. This operand must 
be specified for indexed random and indexed add access 
methods. You must allocate space in main storage for the 
master track index. The length of the master track index is 
determined by the following formulas: 


®@ For singie volume random access methods, 
Length = ENT (key length + 2} 


@ For multivolume random access methods, 
Length = ENT (keylength + 2) 
ENT must be equal to or greater than 4. 


The specified address plus the total length of the area 

must be less than logical X‘E000’ for files that are being 

shared or for files that are being used for external buffers 
(5704-SC2 only). 


/BLKL-number specifies the number of sectors in the index 
buffer. This operand is used only with indexed access 
methods. If this operand is not specified, one sector is 
assumed. For indexed sequential access methods with both 
input and add, the specified index buffer size applies to 
both the input index buffer and the add index buffer. For 
indexed random access methods, the specified buffer size 
applies only to the add index buffer. Increasing the size of 
this index buffer will increase the efficiency of processing 
for arandom file. 


ADKEY-address specifies the address of the leftmost byte 
of an area used to save the highest key in the prime index 
and the highest key in the add index. The area at this ad- 
dress must be equal in length to 2 times KEYi. for each vol- 
ume used by the file. This operand is requirad tor indexed 
add, indexed random input and add, and indexed random 
input, update, and add access methods. !t is ignored it 
specified with other access methods. The specified address 
plus the total length of the area must be less than logical 
X’E000’ for files that are being shared or for files that are 
being used for external buffers (5704-SC2 only). 


EOVK-adadress specifies the address of the leftmost byte of 
an area used to save a key if force end-of-volime is spec- 
ified (by the HIKEY parameter on the FILE OCL state- 
ment) for a multivolume indexed output file. The area at 
this address must be equal in length te KEYL. This cper- 
and ts used only when the multivolume indexed output 


access method is used and force end-of-voiume will be usec!. 
The specified address plus the total jength of the area 


must be less than fogical X’EQOO’ for files that are being 
shared or for files that are being used for external butfers 
(5704-SC2 only). 
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SHR-Y/N, applicable to Program Number 5704-SC2 only, 
allows the user to specify whether or not file sharing is 
permitted on the file. File sharing is permitted, when 
possible, if this parameter is not used, 


EXTBUF-Y/N, applicable to Program Number 5704-SC2 
only, allows the user to have external buffers. If this para- 
meter is not used, external buffering does not occur. 


Construct a Disk Get Interface (SGETD) 


The $GETD macro instruction generates the interface need- 


ed to communicate with disk data management when a 
record is being read from a disk file. To use this macro 
instruction, construct a disk DTF for the file and use the 
$DTFO macro instruction to establish the offsets tor the 
DTF. You must also provide the labels for the necessary 
data management routines through EXTRN statements in 
your programs. The names of the data management mod- 
ules and the functions of the modules are shown in Figure 
11. If you will need to use the data in register 2 at a later 
time, you should save the contents of that register before 
issuing the $GETD macro instruction. 


The code generated by this macro instruction gives con- 
trol to the data management routine; the routine completes 
execution and returns control to the generated code. The 
generated code tests the completion codes returned by data 
management. 


[Name] | $GETD [AC-+ode] } 
[EBAC-code]{ 


(,DTF-address] [,ERR-address]} 
{,EOF-address}] [,NFR-address] 
[,LSTV-address] [,NOKY-address]| 





AC-code or EBAC-code specifies the appropriate access 
method for the file. The EBAC-code is for external buf- 
fering and is valid only for Program Number 5704-SC2. 
One of these parameters must be specified. 


The codes that must be used for the AC-code and the 
EBAC-code parameters are shown in Figure 11. 
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DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent 1/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


EOF -address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
Operand is not supplied, no code is generated to check for 
the end-of-file condition. You must not use this operand 
with random or direct access methods. 


Note: \|f ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation. 


NRF-address must be used only for random and direct 
access methods. It specifies the address in your program 
that is to receive control when a no-record-found condition 
occurs. 


LSTV-address is used when processing a random, offline, 
multivolume file. This operand supplies the address in your 
program which receives control when the requested key is 
too high for the final volume in a multivolume file. 


NOKY-adodress supplies the address in your program that is 
to receive coritrol under either of the following conditions: 


@ The requested key is too low for the current volume 
when processing an indexed random offline multivolume 
file. 


@ The requested key is too high for any volume when 
processing an indexed random online multivolume file. 


This operand is not used with other access methods. 


Construct a Disk Put Interface (SPUTD) 


The $PUTD macro instruction generates the interface need- 
ed to communicate with disk data management when put- 
ting a record to disk or updating a previously retrieved 
record. You must provide a DTF for the file and use the 
$DTFO macro instruction to establish the offsets in the 
DTF. You must also provide, through EXTRN statements 
in your program, the labels of the disk data management 
modules necessary to perform the output operation (see 
Figure 11). If you will need to use the data in register 2 at 
a later time, you should save the contents of that register 
before issuing the $PUTD macro instruction. 
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$GETD 





































$PUTD AC-code System Module 
5444 Jfcoass Mode a 5444 | 5445 | Access Method 
x en | cas | M | SSCSOP SSCFOP | Consecutive Add 
x CAM CAM5 M $$CSOM i S$CFOM 4} Consecutive Add Multivolume 
| x cG CG5 M $SCSIP | SSCFIP | Consecutive Get 
\ x + CGM CGMS | M SSCSIM : SSCFIM | Consecutive Get MVF 
i { j 
| x co CcO5 M $$CSOP | SS$CFOP | Consecutive Output 
x COM COM5 M $$CSOM |} S$SCFOM | Consecutive Output MVF 
x x cu CU5 L $$CSUP | SSCFUP | Consecutive Update 
| x | Xx CUM | CUM5 L $SCSUM $$CFUM | Consecutive Update MVF 
| x DG 0G5 L $SDAID | S$DFID | Direct Get 
i x i DGA DGAS5 L $SDAIB | S$$SDFIB | Direct Get (Binary Keys) 
| x DGAM | DGAM5 L SSDAIT | $SDFIT | Direct Get (Binary Keys) MVF 
x DGM | DGMS5 L $SDAIM $SDFIM | Direct Get MVF 
x x | Do pos L ssoaun | sspeuo | pirect Output 
x x DOA DOAS L $SDAUB | SSDFUB | Direct Output (Binary Keys) 
x x DOAM DOAMS5 L $$D AUT | SSDFUT ! Direct Output (Binary Keys) MVF 
x | x DOM DOMS5 L $SDAUM | $SDFUM Oirect Output MVF 
x x | ou DUS L $SDAUD | $$DFUD | Direct Update 
x x DUA DUAS L $SD AUB | SSDFUB | Direct Update {Binary Keys) 
x x DUAM | DUAM5 L SSDAUT | SS$DFUT | Direct Update (Binary Keys) MVF 
x x DUM DUMS5 L $SDAUM | SSDFUM Direct Update MVE 
x | 1A IAS M $$IOAD | $SiFAD | Indexed Add 
x 1AM {AM5 M SSIOAM SSIFAM : Indexed Add MVF 
x 10 105 M $$1OUT SSIFUT | Indexed Output 
x 10M |OMS M $$1OUM SSIFUM | Indexed Output MVF 
x IR IR5 L SSIRIP SSiGIP | indexed Random Input 
x Xx IRA IRAS ec SSIRAD S$SIGAD {| Indexed Random Add 
x x {RAM IRAM5 L $$IRAM | SSIGAM | indexed Random Add MVF 
Xx x IRBM IRBM5S E SSIRBM SSIGBM | indexed Random Update & Add MVF 
i; x iRM IRM5 L | $$ #RIM SSIGIM indexed Random tnput MVF 
x xX | IRU {URS L $$iRUP | SSIGUP Indexed Random Update 
| x | x IRUA IRUA5 L $$IRUA | $$iGUA | indexed Random Update & Add 
x x IRUM IRUM5 L SSIRUM S$!1GUM indexed Random Update MVF 
| x is IS5 M | SSISIP SSIHIP indexed Sequential Input 
x x ISA ISAS | M ; $SISAD | SSIHAG | indexed Sequential Add 
1 % | X | ISAM | ISAMS | M | SSISAM | SSIHAM | indexed Sequential Add MVF 
| x | x | isBm | iswes | m | ssispm | SsiHBM | indexed Sequential Update & Add MVF 
\ : { 
; =X isL_ | ISLS M | $$ISiL SSIHIL | tedexad Sequential Input Within Limits 
x ISM} ISMS M SSISIM | SSISHIM | inctexed Sequential Input MVE 
x | x | ISU ISU5 Li $sisuP | SSIRUP | indexed Sequential Update 
x { x {SUL | ISULS Ls $$ISUL SSIHUL | Indexed Sequential Update Within Limits 
x | x ISUM | ISUM5 te | $$ISUM | SSIHUM | Indexed Sequential Update MVF 
x | x ISUA | ISUAS M | $SISUA SSIHUA |! indexed Sequential Update & Add 
x ISLM | ISLM5 M $SISIB | SSIHIB Indexed Sequential Input Within Limits MVF 
x x ISUB ISUB5 M $$iISUB S$IHUB =| Indexed Sequential Update Within Limits MVF 
x | ISC ISC5 M SSISIC | SSIHIC indexed Sequential Input Within Changeable Limits 
x \ ISCM ISCM5 M SSISID SSIHiD | Indexed Sequential Input Within Changeable Limits MVF 
xX | x SUC ISUC5 M $$iISUC SSIHUC | indexed Sequentiai Update Within Changeable Limits 
x x iSUD ISUD5 } M $SISUD SSIHUD Indexed Sequential Update Within Changeable Limits MVF 
peck 
































































Figure 11 (Part 1 of 2). Disk Data Management Modules Without External Buffering 


42 





Page of GC21-7608-2 
Issued 29 September 1978 
By TNL: GN21-5649 















AC-code 


5444 | 5448 


System Module 



































Mode 5444 | 5445 Access Method | 
toa 7 
CA cas | M l sswsop $SWFOP Consecutive Add 
CAM CAM5 M S$WSOM SSWFOM Consecutive Add Multivoiume | 
CG CG5 M SSWSIP SSWE IP Consecutive Get | 
CGM CGM5 M i SSWSIM SSWFIM Consecutive Get MVF 
x co COs M $SWSOP SSWFOP Consecutive Output | 
x COM COM5 M S$WSOM SSWFOM Consecutive Output MVF 
x Xx cu CU5 M | $swsuP | SSWFUP | Consecutive Update | 
x xX | CUM | CUMS | M | sswsum | $$wFUM | Consecutive Update MVE 
x DG DG5 M | $SYAID $$YFID Direct Get 
x DGA DGA5 M SSY AIB S$SYFIB Direct Get (Binary Keys) 
x DGAM DGAMS5 M | SSY AIT SSYFIT Direct Get (Binary Keys) MVF 1 
x DGM DGM5 M SSY AIM SSYFIM Direct Get MVF 
x x | DO DOs M | $$YAUD | $$YFUD | Direct Output 
x Xx DOA DOAS5 M | $$Y AUB S$YFUB Direct Output (Binary Keys) 
x X DOAM | DOAMS5 M { S$$YAUT $SYFUT Direct Output (Binary Keys) MVF 
x x DOM DOM5 M $$YAUM SSYFUM Direct Output MVF 
x x DU Dus | M_ | $$vaup | $syruD | Direct Update 
xX Xx DUA DUAS M | $$Y AUB S$YFUB Direct Update (Binary Keys) 
Xx Xx DUAM | DUAMS5 M | $$Y AUT $$Y FUT Direct Update (Binary Keys) MVF 
x xX DUM DUM5 M $$YAUM $$YFUM Direct Update MVF 
x 1A 1A5 M | $$XOAD SS$XFAD Indexed Add 
XxX {AM 1AM5 M SSXOAM SSXFAM indexed Add MVF 
x 10 105 M SSXOUT S$XFUT Indexed Output 
Xx 1OM 1OM5 M S$XOUM | $SXFUM | Indexed Output MVF 
Xx IR IR5 M | SSXRIP | $S$XGIP Indexed Random Input 
x x IRA IRA5 M | SSXRAD | $$XGAD | Indexed Random Add 
Xx x IRAM IRAMS M SSXRAM | S$XGAM | Indexed Random Add MVF 
x Xx IRBM IRBM5 M SSXRBM | $$XGBM | Indexed Random Update & Add MVF 
x IRM IRM5 M $SXRIM | $$XGIM | Indexed Random input MVF 
x x IRU IURS M $SXRUP $$XGUP Indexed Random Update 
X Xx IRUA IRUAS5 M $SXRUA $SXGUA Indexed Random Update & Add 
x x IRUM IRUMS5 M SSXRUM SSXGUM Indexed Random Update MVF 
I 
x IS ISS M SSXSIP | S$XHIP | Indexed Sequential! Input 
x x ISA ISAS M S$XSAD | $SXHAD | Indexed Sequential Add 
Xx Xx ISAM ISAM5 M SSXSAM | $S$XHAM | Indexed Sequential Add MVF 
x Xx ISBM ISMB5 M SSXSBM $$XHBM | Indexed Sequential Update & Add MVF 
x ISL ISL5 M SSXSIL | $SXHIL | Indexed Sequential Input Within Limits 
x ISM ISM5 M $SXSIM $$XSHIM | Indexed Sequential Inout MVF 
x isu ISU5 M $SXSUP | $$X HUP | Indexed Sequential Update 
x ISUL ISUL5 M SSXSUL $SXHUL | Indexed Sequential Update Within Limits | 
x ISUM ISUM5 M $SXSUM | $SXHUM | Indexed Sequential Update MVF i 
x ISUA ISUA5 M $SXSUA | S$XHUA | Indexed Sequential Update & Add | 
x ISLM ISLM5 M $SXSIB SSXHIB | Indexed Sequential Input Within Limits MVF 
x ISUB ISUB5 M $SXSUB $$XHUB | Indexed Sequential Update Within Limits MVE 
x ISC I1SC5 M SSXSIC_ | SS$XHIC | Indexed Sequential Input Within Changeable Limits 
x ISCM ISCM5 M $SXSID | SSXHID | indexed Sequential Input Within Changeable Limits MVF 
x ISUC ISUC5 M SSXSUC | $$XHUC | Indexed Sequential Update Within Changeable Limits { 
x ISUD ISUD5 M $SXSUD S$XHUD Indexed Sequential Update Within Changeable Limits MVF | 
na apr pF 





Figure 11 (Part 2 of 2). Disk Data Management Modules With External Buffering (5704-SC2 only} 
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The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. Com- 
pletion codes are tested and control is returned to your 
program. 


The format of the $PUTD macro instruction is: 


{Name] | $PUTD nese 
[EBAC+ode] 
[,DTF-address} [,ERR-address] 


[,EOX-address] [,DUP-address] 
[,SERR-address] [,KERR-address] 
(,UPD-Y/N] [,LSTV-address] 
[,NOKY-address] [,HKER-address] 





AC-code or EBAC-code specifies the appropriate access 
method for the file. The EBAC-code is for external buf- 
fering and is valid only for Program Number 5704-SC2. 
One of these parameters must be specified. 


The codes that must be used for the AC-code and the 
EBAC-code parameters are shown in Figure 11. 
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DTF-address specifies the address of the DTF associated 
with this file. If this operand is not specified, the address 
is assumed to be in register 2. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


EOX-address supplies the address in your program that is to 
receive control when an end of extent is reached during the 
operation. This operand is entered only when Creating a 
consecutive or indexed file or when records are to be added 
to the file. 


DUP.-address provides the address in your program that is to 
receive control when an attempt to add a duplicate record 
has occurred. This operand is used only with an add access 
method. 


SERR-address is the address in your program where control 
is passed in the event of a sequence error while loading an 
indexed file. 


KERR-adadress specifies the address of your routine to be 
called when an attempt has been made to update a record 
in an indexed file and the attempt would destroy the 
record key. 


UPD-Y/N indicates whether an update is to be performed. 
If this operand is not entered, N (no) is assumed. 


LSTV-address specifies the address in your Program that 
receives control when a requested key is too high for the 
last specified volume. This operand is used only when 

processing an indexed, random, offline, multivolume file. 


NOKY-address supplies the address in your Program that is 
to receive control under either of the following conditions: 


@ The requested key is too low for the current volume 
when processing an indexed, random, offline, multi- 
volume file. 


@ The requested key is too high for any volume when 
processing an indexed random online multivolume file. 


This operand is not used with other access methods. 


HKER.-adaress specifies the address in your program that is 
to receive control when an indexed sequential add multi- 
volume is attempted and the requested key is higher than 
any key presently in the file, but lower than the highest 
permissible key. 


Input/Output Block for Disk ($1OBD) 


This macro instruction generates a disk input/output block 
(108) for use by the disk input/output supervisor. A 30- 
byte IOB is generated for 5444, 5445, and 3340 disk 
devices. For a detailed description of the disk IOB, see 
Appendix C: Disk Input/Output Block. 


The format of the $1OBD macro instruction is: 
[DISK-5444/5445/3340] [,CYL-number] 


[,SCTR-number} [,HEAD-number} 
{,NUM-number] [,BUFF-address] 


(,Q-number] [,ERREC-1OS/USER]} 
[,LOG-Y/N] [,VER-Y/N] [{,CHN-address] 
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DISK-5444/5445/3340 specifies whether the disk device 
being used is the 5444 Disk Storage Drive Model 1, 5445 
Disk Storage, or the 3340 Direct Access Storage Facility. If 
a device is not specified, 5444 Disk Storage Drive Model 1 
is assumed. 


CYCL-number indicates the beginning cylinder to be 
accessed. You can specify the cylinder by a decimal num- 
ber (0-199) or a hexadecimal number (X‘00‘-X’C7’). If this 
operand is not entered, X‘FF’ is assumed. You must then 
insert the correct number into the IOB before performing 
the input/output operation. This can be done through the 
macro used to initiate the 1/O operation. 


SCTR-number specifies the first sector to be accessed. The 
number specified must be a decimal from 1 through 48 for 
the 5444 disk drive, from 1 through 20 for the 5445 disk 
storage, or from 1 to 48 for the 3340 disk drive. If this 
operand is not entered, X‘FF’ is assumed. You must then 
insert the correct number before performing the input/ 
output operation. You can specify the sector through the 
$RDD and $WRTD macro instructions. 


HEAD-number is specified only for the 5445 or 3340 disk 
storage drives. It specifies the head to be used with the 
cylinder and sector when an I/O operation is performed. 
The number specified may be decimal (0-19) or hexa- 
decimal (X’00’-X'13‘). If this operand is omitted, X'FF’ 
is assumed and the value must be updated when the {/O 
operation is performed. 


NUM-number specifies the number of sectors used. You 
may specify the number in either decimal or hexadecimal 
form. If this operand is not entered, one sector is assumed. 


BUFF-adaress is the address of the leftmost byte of your 
data area. If this operand is omitted, X’FFFF’ is assumed, 
and you must update the IOB before performing the input/ 
output operation. 


Q-number specifies the drive on which the record is located. 


“You may specify the disk drive alone F1, R1, F2, R2, D1, 


D2, D3/D31, D32, D33, D34, D4/D41, D42, D43, and D44 
or you may specify the hexadecimal Q-code in the form 
Q-X‘nn’‘, where nn is a valid hexadecimal Q-code. The 
valid Q-codes are shown in Figure 12. If you specify 

only the disk drive, you must set the reac! “write bits (the 
last four bits of the Q-code) before you can perform 

the I/O operation. This can be done through the $RDD 

or $WRTD macro instructions. 


’ 


Note: D31, D32, D33, D34, D41, D42, 043, and D44 
are for 5704-SC2 only. 


Macro Instruction Statements 45 
Disk Device Support 


1/0 





Figure 12. Q-Byte Hexadecimal Settings! 


ERREC-IOS/USER indicates whether the input/output 
supervisor is to handle error recovery. If you specify |OS, 
the supervisor handles error recovery and retries the opera- 
tion when errors occur. If you specify USER, the supervisor 
does not retry the operation and returns control to you. If 
this operand is not specified, 1OS is assumed. 


LOG-Y/N indicates whether the |/O supervisor is to log 
errors that occur during the operation. If you specify Y 
(yes), error conditions are logged on the system pack. This 
information is used by IBM customer engineers. N (no} 
indicates no logging is to be done for this 1OB. If this oper- 
and is not entered, Y is assumed. 


VER-Y/N is used for output operations. Y (yes) indicates 
the written data should be verified; N (no) indicates it 
should not. If this operand is omitted, Y is assumed. 


CHN-address specifies the address of the leftmost byte of 
the next [OB for the operation if more than one IOB is 
required. 


: Figure 12 applies only to 5704-SC1. For 5704-SC2, you can 
specify only the disk drive (F7, R1, etc.) with the Q parameter, 
and read/write bits are set with $RDD or $WRTD. 
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Input/Output Block Offsets ($IOED) 


This macro instruction generates equates to establish labels 
for the disk IOBs. These labels are offsets from the begin- 
ning of the |OB and are used as displacements from the be- 
ginning of the 1OB when you wish to refer to one of the 
fields. The labels generated by this macro instruction are 
given with the fields of the [OB in Appendix C: Disk 
Input/Output Block. To avoid duplicate labels, you should 
use this macro instruction only once in a program. 


The format of the $1OED macro instruction is: 


[Jee 


Read from Disk ($RDD}) 


This macro instruction generates an interface to the disk 
input/output supervisor that is to read from the disk device. 
When using this macro instruction, you must: 


@ Provide an 10B and use the $1OED macro instruction 
to establish the offsets in the IOB. 


@ Wait for the completion of the input operation (using 
$WAIT). 


@ Check for end of extent when the record is received — 
completion code of X‘70’ (SCPEOX) at SDFCMP in the 
DTF. 


If both reading and writing for a program are to be per- 
formed using a single OB, the bits of the Q-byte are altered 
to indicate an invalid operation. In this case, you must set 
off the bits of the Q-byte for all but the first read (or write) 
operation in the program. 


If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 


the $RDD macro instruction. 


The format of the SRDD macro instruction is: 


[Name}} $RDD 1OB-address,CS-address, NSECT-number 
{,DISK-5444/5445/3340] 





/OB-address provides the address of the leftmost byte of 
the 1OB which you created through your $IOBD macro 
instruction. The label provided must be the same as the 
name specified on your $1!0BD macro instruction. 


CS-adaress is the address of the rightmost byte of the main 
storage area containing the disk cylinder/sector address of 
the area you want to read. The cylinder/sector address for 
use with the 5444 is a two-byte, hexadecimal number. The 
first byte specifies the cylinder; the second specifies the 
sector. For use with the 5445, or 3340, a three-byte hexa- 
decimal disk address is provided through this entry. The 
first byte specifies the cylinder; the second, the head 
number; the third, the sector. 


NSECT-number indicates the hexadecimal number of sectors, 


minus one, to be read in this operation. 


DISK-5444/5445/3340 specifies whether the operation is 
on a 5444, a 5445, or a 3340 disk drive. If this operand is 
omitted, 5444 is assumed. 


Write to Disk (SWRTD}) 


This macro instruction generates an interface to the disk 
input/output supervisor needed to write records to disk. 
When you use this macro instruction, you must: 


@ Provide an IOB, and use the $10ED macro instruction to 
establish the offsets in the lOB. 


@ Wait for the completion of the output operation (using 
$WAIT). 


If both reading and writing for a program are to be 
performed using a single OB, the bits of the Q-byte are 
altered to indicate an invalid operation. In this case, you 
must set off the bits of the O-byte for all but the first read 
(or write) operation in the program. 


If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 


the macro instruction. 


The format of the SWRTD macro instruction is: 


[Name]] SWRTD] !OB-address,CS-address,NSECT-number 
[L,DISK-5444/5445/3340] 


Page of GC21-7608-2 

Issued 28 March 1980 

By TNL: GN21-5700 
/OB-address provides the address of the disk 1OB for this 
operation. The address is the name specified oi the related 
$IOBD macro instruction. 


CS-address is the address of the rightmost byte of the main 
storage area containing the disk cylinder/sector address of 
the area to which you want to write. The cylinder/sector 
address for use with the 5444 is atwo-byte hexadecimal 
number. The first byte specifies the cylinder; the second 
specifies the sector. For use with the 5445 or the 3340, 

a three-byte hexadecimal disk address is provided through 
this entry. The first byte specifies the cylinder; the second, 
the head number; the third, the sector. 


NSECT-number specifies the hexadecimal number of disk 
sectors, Minus one, to be written. 


DISK-5444/5445/3340 specifies whether the operation is 
on a 5444, a 5445, or a 3340 disk drive. If this operand is 
omitted, 5444 is assumed. 


Wait for Disk 1|OS Completion (SWAIT) 


This macro instruction is used with the $RDD and $WRTD 
macro instructions. It generates the code that allows you 

to wait for completion of the disk 1OS operation. You pro- 
vide the label of the associated 1OB and an address to receive 
control in the event of an error. 


If you will need to use the data in register 1 at a later time, 
you should save the contents of that register before issuing 
the SWAIT macro instruction. 


The format of the SWAIT macro instruction is: 


{[Name]} SWAIT | [1OB-label] [,ERR-address]} 


/OB-label is the name assigned to the IOB in the $1OBD 
macro instruction. This same 1OB must have previously 
been specified in either aS$RDD or $WRTD macro instruc- 
tion. If this operand is not entered, the address is assumed 
to be in register 1. 


ERR-address specifies the address of the routine in your 
program that handles errors detected in the operation. If 
this operand is not entered, no error checking is performed, 
and you should check the return code in your program to 
determine the outcome of the operation. 
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3741 Device Support 


This section describes the macro instructions that support 
the directly attached 3741 Data Station Model 1 or 2 or 
Programmable Work Station Model 3 or 4. The following 
functions are provided: 


@ Build a pre-open DTF and assign its offsets. 


® Build the interface required to read input records from 
the 3741 device via a GET. 


@ Build the interface required to write output records to 
the 3741 device via a PUT. 


The DTFs provide information to the data management 
routines that perform the input/output operations. The 
interfaces to these operations are provided through the 
3741 macro instructions. 


Define the File for 3741 (SDTFK) 
The DTF provides information needed to allocate, open, 
and access a file on the 3741. This macro generates the 


DTF for this purpose. 


The format of the $DTFK macro instruction is: 








$DTFK NAME-filename,R ECL-number ,|O-address 
[,AC1/O] {,RCAD-address] [,BUFNO.1/2] 
[,CHN-address] [,UP-mask] 






NAME-filename specifies the name of the file. The name 
must be eight characters or less in length. This operand 
must be specified. 


RECL-number specifies the decimal length (from 1 to 128) 
of the logical record. This operand must be specified. 


/O-address provides the address of the leftmost byte of an 
area in main storage that contains the buffers and the IOB. 
This operand must be specified. The amount of storage 
must be the record length plus 26 times the BUFNO. 


AC-1/O specifies whether the DTF is input or output. If 
this operand is not specified, input is assumed. 


RCAD-address specifies the address of the leftmost byte 
of the logical record. If this operand is not entered, 
X'FFFF’ is assumed. 
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BUFNO-1/2 allows you to specify either one or two buf- 
fers. If this operand is omitted, one buffer is assumed. 


CHN-adadress indicates the address of the next DTF in the 
chain of DTFs. If there is no DTF chain, the operand is 
omitted and X’FFFF’ is assumed. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 


Note: \nformation on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and /BM 
System/3 Model 15 System Control! Programming Concepts 
and Reference Manual (for Program Number 5704-SC2), 
GC21-5162. 


Construct 3741 Get Interface (SGETK) 


The $GETK macro instruction generates the interface need- 
ed to communicate with the 3741 data management when a 
record is being read from the 3741. To use this macro 
instruction, construct a 3741 DTF for the file and use the 
$DTFO macro instruction to establish the offsets for the 
DTF. You must also provide an EXTRN statement with 
the label SSCPIP to use this macro. If you will need to 

use the data in register 2 at a later time, you should save 
the contents of that register before issuing the $GETK 
macro instruction. 


The code generated by this macro instruction gives control 
to the data management routine. The data management 
routine completes execution and returns control to the 
generated code. 


The format of the $GETK macro instruction is: 


$GETK| EOF-address [,DTF-address] [,ERR-address] 


EOF-address specifies the address in your Program that 
receives control when the end of file is detected. This 
Operand must be specified. 


DOTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address supplies the address in your program where 
control is passed if the controlled cance! option is taken in 
response to a permanent I/O error. If this operand is 
omitted, no code is generated to check for the controlled 
cancel completion code. 


Construct 3741 Put Interface (SPUTK) 


The $PUTK macro instruction generates the interface needed 
to put a record on the 3741. You must provide a DTF for 
the file and use the $DTFO macro instruction to establish 
the offsets in the DTF. You must also provide an EXTRN 
statement in your program with the label $$CPOP to use 
this macro. If you will need to use the data in register 2 

at a later time, you should save the contents of that register 
before issuing the $PUTK macro instruction. 


The code generated by this macro instruction gives control 
to the data management routine. The data management 
routine completes execution and returns control to the 
generated code. 


The format of the $PUTK macro instruction is: 


$PUTK]| [DTF-address] [,ERR-address] 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is 
omitted, no code is generated to check for the controlled 
cancel completion code. 


Tape Device Support 


This section describes the macro instructions that support 
the IBM 3410/3411 Magnetic Tape Subsystem. The follow- 
ing functions are provided: 


@ Build a pre-open DTF for tape and assign its offsets. 


® Build the interfaces required to read input records from 
a tape device via a get or a read. 


@ Build the interfaces required to write output records to 
a tape device via a put or a write. 


@ Build the interface required to issue tape control 
commands. 


@ Wait for completion of read, write, or tape control 
operations. 


The tape DTFs provide information to the tape data man- 
agement routines that perform the input/output operations. 
These operations are provided through the tape support 
macro instructions. 


Define the File for Tape (SDTFT) 


The DTF provides information needed to allocate and open 
a tape device. This macro instruction generates the code 
that builds the tape DTF. See Appendix B: Define the 
File Control Blocks for a description of the pre-open and 
post-open DTFs. 


The format of the $DTFT macro instruction is: 





[Name] | $DTFT | NAME-filename,|O-address,BLKL-number, 


RECL-number [,UP-mask] [,AC-IN/OUT] 
[,CHN-address] [,BASIC-Y/N] 
[,RCAD-address] [,MODE-LOCATE/MOVE] 
(,MBUFF-Y/N] [,RECFM-code] 
[,L!OA-number] [.SPAN-Y/N] [,CODE-A/E] 
{[,OSET-B/number] [,END-code] LMVF-Y/N] 








NAME-filename is a required operand specifying the name 
of the tape file. The filename can be up to eight characters 
in length and must be the same as the name of the // FILE 
statement. 
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/O-address specifies the address of the leftmost byte of the 
main storage area used to contain all buffers and IOBs. This 
operand is required. The length of the area specified by 
this address is specified in the LIOA operand. 


Note: \|f basic data management routines are used to 
Process the file, this operand should point toa 40-byte area 
to contain the tape IOB. 


BLKL-number is a required operand that specifies the deci- 
mal block length for the file. The minimum block length 
allowed is 18 bytes. if a shorter length is specified, 18 is 
assumed. For files with fixed-length records, the block 
length must be a multiple of the record length; for files with 
variable-length records, the block !ength must equal the 
length of the longest record plus eight. 


Note: If basic tape data management is used, the block 
length in the DTF (SDFBKL) must be updated after the file 
is opened and before any read or write Operation is per- 
formed. The field must also be updated before any subse- 
quent read or write if the length used is different than the 
previous read or write. 


RECL-number is a decimal value specifying the length of a 
logical record in the file. If variable-length records are used 
for the file, the record length specified must be equal to the 
longest record plus four. The minimum record length when 
variable-length records are used is four, which results in 
zero-length records. The minimum record length for files 
using fixed-length records is 18. This operand is required. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in 
the UP-mask are also on in the external indicators set on by 
the SWITCH statement, the file will be opened. If the 
UP-mask is all zeroes or not used, the file will be uncondi- 
tionally opened. 


Note: Information on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control Programming Reference Manual for Pro- 
gram Number 5704-SC1, GC21-5077, and /BM 

System /3 Model 15 System Control Programming Con- 
cepts and Reference Manual for Program Number 5704- 
$C2, GC21-5162. 
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AC-IN/OUT specifies the type of file. IN specifies an input 
file; OUT, an output file. If this operand is not entered, IN 
(input) is assumed. 


Note: The operation code in the Tape DTF will be initial- 
ized according to the entries specified (or defaults) of the 
AC and BASIC operands, as follows: 


AC-IN AC-OUT 
BASIC-Y | Read forward 


CHN-address specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and X‘FFFF’ assumed. 
















BASIC-Y/N specifies whether this DTF uses the basic access 
method. If this operand is not entered, N (no) is assumed. 


Notes: 

1. BASIC-Y must be specified if any of the following macro 
instructions are used to process the file: $RDT, SWRTT, 
SCTLT or $WTT. 

2. If you process ASCII files using the basic access method, 
you must translate the characters in your program. 

3. Muiltivolume files are supported with the basic access 
method, but the EXTRN statement that is provided 
must be $$BTMM for multivolume support. $$BTAM 
and $$BTMM should not be used in the same program. 
$$BTMM supports both single and multivolume files. 

4. Deferred cpen is not allowed with the basic access 
method. 


RCAD.-address specifies the symbolic record area address. 
This operand is required for all operations using the basic 
access method. If standard data management is used, this 
operand is required for an output operation and for an 
input operation using move mode. 


MODE-LOCATE/MOVE indicates whether the locate mode 
or move mode is used. If this operand is not specified, 
MOVE is assumed. When locate mode is specified, the record 
address (RCAD-address) is set to the address of the record 

in the buffer. When move mode is used, records are moved 
from the buffer to the location specified by the record 
address. 


Locate mode is valid only for input files. This operand 


should not be used if BASIC. Y is specified 


RECFM-cede specifies the record format used for the file, 
The codes and their meanings are: 


Code Record Format 

F Fixed, EBCDIC or ASCII 

FB Fixed blocked, EBCDIC ar ASCII 
Vv Variable, EBCDIC 

VB Variable blocked, EBCDIC 

D Variable, ASCH 

DB Variable blocked, ASCII 


If this operand is not specified, F is assumed, 


MBUFF-Y/N indicates whether more than one buffer is 
used. If this operand is not specified, N (no} is assured. 
The number of buffers is determined by the length of the 
1/0 area, specified by the LIOA operand. This operand 
should not be used if BASIC-Y is specified. 


L/IOA-number is the total decimal length of the 1/O area if 
more than two buffers are required (MBUFF-Y), If the 
number specified is zero or if this entry is omitied, two 
buffers are allocated in the 1/O area. If this entry is net 
zero, as many buffers as possible are allocated in the |/O 
area. 


The following formula can be used to determine the length 
of the I/O area: 

Length of the 1/O area= (40 + black length) times 
(number of buffers} 


This operand should not be used if BASIC-Y is specified. 


SPAN-Y/N specifies whether spanned records are used. HH 
spanned records are used, BASIC-Y must also he specified, 
If this operand is omitted, N (no) is assumed. Specifying 
SPAN-Y causes the spanned record bit in the tape tatel to 
be set on. When you use SPAN-Y, you must spar the ree: 
ords from block to block. 


CODE-A/E specifies whether the file is an EBCOIUC file or 
ASCII file. If the file is an EBCDIC file, specity CODE-E, 

If the file is an ASCII file or can be either ASCII or EBCDIC, 
specify CODE-A. If this operand is not entered, & is 
assumed. 


OSET-B/number specifies the buffer oifset of an ASCH 
block. B indicates that the first four bytes of the block con 
tain the decimal block length and no buffer atts 
ent. B is valid only when RECFM.-D or RECE MDB is also 
specified. Only OSET-B or OSET-00 are valid for output 
files. OSET-numbei specifies, in decimal, the length of the 
buffer offset for the ASCII block. This buffer offset is 
skipped over when the record is supplied ta your program. 
The maximum valid specification is OSET 99 
and is not specified, zero is assumed. 


1S pres 


f this oper- 
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END-code specifies the tape control actions to be taken 
when the file is closed. The valid codes and their meanings 
are: 


Code Action 

REWIND Rewind the tape 

UNLOAD Rewind and unload the tape 
LEAVE No action taken 


If this operand is not entered, REWIND is assumed. 


MVF-Y/N specifies whether this file has multivolume tape 
output. If this operand is not specified, Y (yes) is assumed. 


Construct a Tape Get Interface ($GETT) 


Tne $GETT macro instruction generates the interface 
required to communicate with tape data Management when 
a record is being read from a tape file. To use this instruc- 
tion, you must construct a tape DTF for the file and use 
tive $DTFO macro instruction to establish the offsets in the 
DTF. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $GETT macro instruction. 


You must also provide the labels for the necessary data 
management routines through EXTRN statements in your 
program. The names and functions of the data management 
routines are shown in Figure 13. 


Module 
Name Type of File Being Processed 





$$CSIT EBCDIC fixed input 


$$CSOT | EBCDIC fixed output 
$SCSIA EBCDIC or ASCII fixed input 
$$CSOA | EBCDIC or ASCII fixed output 
$$CSTI EBCDIC fixed or variable input 


$$CSTO 


EBCDIC fixed or variable output 


$SCSAI 





EBCDIC or ASCII fixed or variable input 


$SCSAO | EBCDIC or ASCII fixed or variable output 





Figure 13. Tape Data Management Modules 
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The code generated by this macro instruction gives control 
to the data management routine; the routine completes 
execution and returns control to the generated code. If the 
ERR or EOF operand is specified, the generated cade tests 
the completion code returned by data management and 
branches to your routine, If reading variable length records 
tape data management returns the length of the record at 
label $DFCRL in the DTF. 


' 


The format of the $GETT macro instruction is: 


[Name] ]| SGETT | MODULE-name!,DTF-address] 


[,RCAD-address} [,OPC-Y/N] 
[,ERR-address] {,EOF-address] 





MODULE-name is a required operand that specifies the 
module name of the tape data management subroutine. 
Following are the module names used and the types of files 
they will process: 


$$CSIT EBCDIC fixed input 

$$CSIA EBCDIC or ASCII fixed input 

$$CSTI EBCDIC (fixed or variable) input 

$$CSAI EBCDIC or ASCII (fixed or variable) input 


An EXTRN must be provided for the module name that is 
used. 


DTF-address indicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


RCAD.-address specifies the address of the leftmost byte of 
the logical record area. If this operand is not entered, the 
address of the record area is assurned to be in the DTF at 
$DFLRA. 


OPC-Y/N specifies whether to generate the code te set the 
operation code. If this operand is not entered, N (no) is 
assumed, and the operation code is not modified. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent I/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 


EOF-address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. 


Note: !f ERR or EOF addresses are not specified, you 
should check the return code in your program to determine 
the outcome of the operation 


Construct a Tape Put Interface (SPUTT) 


This macro instruction generates the interface needed to 
communicate with tape data Management when writing a 
record to tape. You must provide a DTF for the file and 
use the SOTFO macro instruction to establish the offsets 
inthe DTF. You must also provide, through EXTRN 
statements in your program, the labels of the tape data 
management modules necessary to perform the output 
operation (see Figure 13). 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $PUTT macro instruction. 


The code generated by this macro instruction gives control 
to the data management routine. The routine completes 
execution and returns control to the generated code. If 
the ERR operand is specified, the generated code checks 
the completion code for errors and branches to your error 
routine if errors occurred. 


The format of the SPUTT macro instruction is: 








[Name]! $PUTT | MODULE-name [,DTF-address] 
[,RCAD-address] [,OPC-Y/N] 


[,LENAD-address] [,ERR-address] 






MODULE-name, is a required operand, and specifies the 
name of the tape data management subroutine to be used. 
Following are the module names used and the type of. 
files they will process: 


$$CSOT EBCDIC fixed output 

$$CSOA EBCDIC or ASCII fixed output 

S$CSTO EBCDIC fixed or variable output 

$$CSAO EBCDIC or ASCII fixed or variable output 


DTF-address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not specified, the 
address is assumed to be in register 2. 


LENAD.adaress specifies the address of the rightmost byte 
of a two-byte area which contains the length of the current 
record. This operand is used only for variable files. If this 
operand is not specified, the length of the record is 
assumed to be in the DTF at $DFCRL. 


RCAD.-adaress specifies the address of the leftmost byte of 
the record to be put. If this operand is not entered, the 
record address is assumed to be in the DTF at label $DELRA. 


OPC-Y/N specifies whether to generate the code to set the 
operation code. If this operand is not entered, N (no) is 
assumed, and the operation code is not modified in the 
DTF. 


ERR-adaress specifies the address in your program where 
control should be passed if a permanent |/O error occurs. 
If this operand is not entered, no permanent !/O error 
checking code is generated and you should check the 
return code in your program to determine the outcome of 
the operation. 


Read from Tape ($RDT) 


This macro instruction generates an interface to basic tape 
data management to read from a tape device. When using 
this macro instruction, you must: 


© Provide a tape DTF and use $DTFO to establish the 
offsets in the DTF. 


@ Wait for completion of the input operation and ches:k 
for end-of-file by using the SWTT macro instruction. 


@ Provide EXTRN statements in your program for tiie 
basic tape data management module ($$BT AM or 
$$BTMM) and for the entry point to the read routine 
in that module (DMBTRW). 


!f you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $RDT macro instruction. The generated code for this 

macro instruction uses register 2. 


The code generated by this macro instruction branches to 
basic tape data management to begin the read operation. 
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The format of the $RDT macro instruction is: 





SRIVT {MTF-address] [,RCAD-address] 
| DIRECT-FORW/BACK | 









[Name] 


OTF address specifies the address of the leftmost byte of 
the DTF for the file. If this operand is not entered, the 
address is assumed to be tn register 2. 


RCAD-addreéss specities the address of the leftmost byte of 
the recor area. If this operand is not specified, the address 
is assurned tu be in the DTF at SDFELRA. 


DIRECT § ORW or BACK specifies the direction of the 
read and cattses the operation code in the DTF to be set 
(see AC operand of SOTFT). If this operand is not 
entered, the oueration code is unchanged. 


Write to fape (SWATT) 


This macro tistiuction generates the intertace to basic tape 
data toanage ment needed to write records to tape. When 
you. 9 thts tarry instruction, you rust: 


@ Provide a OTF for the file and use the $2 TFO macro 
misthuciion io astablish the offsets in the DTF. 


® Wart tor the completion of the 1/O operation by using 


oA P niacre mstruction, 


e 


wide XX T&M statements in your program for the 
basic lays, date nvanagement module ($$BTAM or 
SSBKTMM}) and to: the entry point to the write routine 
we tit module (DMBTRW). 


I vod will oged to use the data in register 2 at a later time, 





you should save the contents of that register before issuing 
the SWEET facro instruction, because the generated code 
fot that taacro mstruci uses register 2. 


The code generated by this macro instruction branches to 
basic tape cute management to start the operation. 


The format of the $WRTT macro instruction is: 





{DTF-address} [,RCAD-address] 
|,OPC-Y/N] 
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DTF-address is the address of the leftmost byte of the DIF 
for the file. If this operand is not specified, the address of 
the DTF is assumed to be in register 2. 


RCAD-address specifies the address of the leftmost byte of 
the record area. If this operand is not specified, the address 
is assumed to be in the DTF at $DFLRA. 


OPC-Y/N specifies whether the write operation code in the 
DTF is to be set. If N (no) is specified or if this ope: and 1s 
not entered, the operation code is not modified in the DTF. 


Contro! Command for Tape (SCTLT) 


This macro instruction generates the interface to basic 
tape data management to issue control conimands to the 
tape device. It is not used to get records from or put 
records out on a tape file. To use this macro instruction, 
you must: 


@ Provide a DYF for the file on the tape device and use 
the $DTFO macro instruction to establish the offsets in 
the DTF. 


@ Wait for completion of the operation by issuing the 
SWTT macro instruction. 


@ Provide EXTRN statements in your program for the 
basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the control routine 
in that module (DMBTPS). 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $CTLT macro instruction. 


The code generated by this macro instruction branches to 
the basic tape data managernent to initiate the operation. 


The format of the $CTLT macro instruction is: 


(Name] | $CTLT | [DTF-address} [,OPC-code] 











DTF-address specifies the address of the leftmost byte of 
the DTF for the file on the tape device. If this operand is 
not specified, the address of the DTF is assumed to be in 

register 2. 


OPC-code specifies the Control operation to be performed. 
If this operand is not specified, no code is generated to 
modify the operation code in the DTF. The valid codes 
and their meanings are: 


Code Operation 

FSF Forward space file 

FSB Forward space block 
BSF Backspace file 

BSB Backspace block 

REW Rewind tape 

RUN Rewind and unload tape 
WTM Write tape mark 


Wait For Tape 1/O Completion (SWTT) 


This macro instruction is used with the $RDT, SWRTT, 
and $CTLT macro instructions, It generates the linkage to 
basic tape data management to wait for the completion of 
operations that have been initiated. You must Provide the 
address of the tape DTF for the file and use the SDTFO 
macro instruction to establish the offsets for that DTF. 
You must also provide EXTRN statements in your program 
for the basic tape data management module ($$BTAM or 
$$BTMM) and for the entry point to the wait routine in 
that module (DMBTWT). You may also provide addresses 
where control is to be returned in the event of a permanent 
1/O error, end-of-file condition, or end-of-tape condition. 


if you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $WTT macro instruction. 


The generated code from this Macro instruction checks the 
completion code in the DTF to determine the outcome of 
the operation. When an abnormal completion is detected, 
control is passed to the appropriate address in your program, 
(if you have specified ERR, EOJ, or EOT) or to the next 
instruction in your Program. 





The format of the $WTT Macro listruction is: 


[DT F-address] [,ERR-address] 
{,EOF address j {,EOT-address] 
[,WLRS-address | UWLRL-address] 












DTF-address specifies the address of the leftmost byte in 
the DTF for the file. If this operand is omitted, the 
address of the DTF is assumed to be in register 2. 


ERR-address is the address of the routine in your program 
that receives control when a controlled cancel is indicated 
in the completion code. If this operand is not entered, the 
controlled cancel is ignored and control returns to the 
next instruction in your program. 


EOF-address specifies the address of your routine that 
receives control when end-of-file occurs. }f this operand is 
omitted, the end-of-file condition is ignored and control 
returns to the next instruction in your program. 


EOT-address is the address of the routine in your program 
that receives control when end-ot- tape is detected. If this 
operand is not specified, the condition is ignored and con- 
trol returns to the next instruction in your program. 


WL RS-address specities the address of the routine that is 

to get control when a record that is too short is read. This 
operand should be used when waiting for a completion of a 
read operation. 


WL RL-address specifies the address of the routine that 
should get control when a record that is too long is read. 
This operand should be used when waiting for the comple- 
tion of a read operation. 


Note: \f ERR, EOF, EOT, WLRS, or WLRL addresses are 


not specified, you should check the return code in your 
Program to determine the outcome of the Operation. 
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Device Independent Support 


This section describes the macro instructions that support 
device independent files. Device independent data manage- 
ment supports sequential files on disk, tape, and card 
devices, and on printers. The device type is determined at 
execution time according to data on the file card. The fol- 
lowing functions are provided: 


@ Build a pre-open DTF for device independent data 
management. 


@ Build the interface required to get a fixed length record 
from a file. 


@ Build the interface required to put a fixed length record 
to a file. 


The device independent DTF provides information to the 
device independent data management routines that perform 
the input/output operation. 


Define the File for Device Independent ($DTFI) 


The $DTFI macro instruction provides information needed 
to allocate, open and access a device-independent file. This 
macro instruction generates the code that builds a device- 
independent DTF. See Appendix B: Define the File Con- 
trol Blocks for a description of the device-independent 
DTFs. To use this macro instruction, you must use the 
$DTFO macro instruction to establish the offsets for the 
DTF. 


The format of the $DTFI macro instruction is: 


{Name] | $DTFi NAME-filename, RECL-number, 1O-address 


L.AC-IN/OUT] [,BLKL-number]} 


[,RCAD-address] [,BUFNO-1/2] 
[,CHN-address] [,UP-mask] 





NAME-filename specifies the name of the file. The name 
can be eight characters or less in length. This operand must 
be specified. 


RECL-number is a decimal value specifying the length of a 
logical record in the file. This operand is required. 
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Note: The record length will be changed by the device- 
independent open to accommodate the physical device size. 
If the record length is greater than the physica! device 
length, the record length is changed to the device length. 
For output files, this means that the number of positions 
by which the size of the logical record area exceeds the 
device size will be truncated from the rightmost positions 
of the logical record. For input files, this means that the 
contents of the positions by which the size of the logical 
record area exceeds the device size will not be changed. If 
the record length is less than the physical device length, the 
record length is not changed and, for output files, the 
physical record will be padded with blanks. 


1O-address specifies the address of the I/O area. This area 
must be on a 256-byte boundary for each buffer. This I/O 
area must be at least equal in length to block length plus 40 
bytes, or be 286 bytes, whichever is greater. This operand 
is required. 


AC-IN/OUT specifies the type of file. IN specifies an input 
file; OUT, an output file. 


If this operand is omitted, IN (input) is assumed. 


BLKL-number specifies the decimal block length for the 
file. 1f this operand is not specified, the value of the record 
length (RECL) is assumed. 


Note: For tape files, the actual block length is used. For 
disk files, the block length is rounded down to a multiple of 
256. The block length is not used for unit record devices. 


RCAD.-address specifies the address of the leftmost byte of 
the logical record. If this operand is not entered, X‘FFFF’ 
is assumed and the address must be supplied when an opera- 
tion is requested. 


BUFNO-1/2 specifies the number of buffers to be used. If 
this operand is not specified, 1 is assumed. 


CHN-adadress specifies the address of the next DTF in the 
chain of DTFs. If there is no DTF chain or if this DTF is 
the last DTF in the chain, this operand should be omitted 
and the end of chain (X‘FFFF’) assumed. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

a5 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is com- 
pared to the external indicators set on by the SWITCH 
statement for conditionally opening files. If the bits that 
are on im the UP-mask are aiso on in the external indicators 
set on by the SWITCH statement, the file wili be opened. 
if the UP-mask is all zeroes or not used, the file will be 
unconditionally opened. 


Note: '!nformation on setting externa! mdicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Contre! Programming Reference Manual (for 
Program Nurnber 5704-SC1}, GC21-5Q77, and in the 

(Bil Svstem/3 Model 15 System Control Programming 
Concepts and Reference Manual 


Construct a Device-Independent Get Intertace (SGETI) 


The SGETI macro instruction generates the interface need- 
ec to communicate with device-independent data manage- 
ment when a record is being read. To use this macro 
instruction, you must construct a device-independent 

DTF far the fite ard use the $DTFO macro instruction to 
estabich tne offsets in the DTF. In addition, you must 
provide the labels for the necessary data management 
routines through an EXTRN to $SCSII in your programs. 


If you wail reed to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 


the SGET! instruction, 


The format of the $GETI macro instruction is: 





t 
it [Name] | SGETt {DTF-address} [,RCAD-address] 
| iP 
' L.ERR-address} [,EOF-address} 


ae 








OTF audress indicates the address of the leftmost byte of 
the OTF iur inis file. If this operand is not specified, the 
address is assumed to be in register 2. 


ACAD-address specifies the address of the leftmost byte 
of the record area. if this operand is not entered, the 
address is assumed to be in the OTF at SDFLRA. 


ERR-address supplies the acidress in your program where 
control is passed if the contrulied cancel option is taken in 
response ta a permanent 1/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code. 
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EOF -address specifies the address in your program that 
receives control when the end-of-file is detected. If this 
operand is not supplied, no code is generated to check for 
the end-of-file condition. 


Note: \f ERR or EOF addresses are not specified, you 
should check the return code in your program to deter- 
mine the outcome of the operation. 


Construct a Device-Independent Put Interface ($PUTI) 


The SPUTI macro instruction generates the interface need- 
ed to communicate with device-independent data manage- 
ment when writing a record. To use this macro instruction, 
you must construct a device-independent DTF for the 

file and use the $DTFO macro instruction to establish the 
offsets in the DTF. In addition, you must provide the 
labeis for the necessary data Management routines through 
an EXTRN to $$CSIO in your programs. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $PUTI instruction. 


The format of the $PUTI macro instruction is: 






[|DTF-address] {,RCAD-address] 
{,ERR-address} {,EOX-address] 


[Name] 





DTF -addressindicates the address of the leftmost byte of 
the DTF for this file. If this operand is not specified, the 
address is assumed to be in register 2. 


RCAD.-address specifies the address of the leftmost byte of 
the record area. If this operand is not entered, the address 
is assumed to be in the DTF at $DFLRA. 


ERR-address supplies the address in your program where 
control is passed if the controlled cancel option is taken in 
response to a permanent 1/O error. If this operand is omit- 
ted, no code is generated to check for the controlled cancel 
completion code and you should check the return code in 
your program to determine the outcome of the operation. 


EOX-address specifies the address of the routine that 
receives control when the end of extent on disk is reached. 
The file will not contain the record for which the put was 
requested. 


If this operand is not specified, the code that checks for 
the end of extent completion code is not generated. 


Macro Instruction Statements 57 
Device-!ndependent Support 


Page of GC21-7608-2 
Issued 29 September 1978 
By TNL. GN21-5649 


CRT/Keyboard 


This section describes the macro instructions that support 
the CRT/Keyboard. This support can be grouped in two 
Categories: display support and program function key sup- 
port. It provides the following capabilities: 


@ Builds a pre-open OTF for the CRT/Keyboard data 
management. 


@ Builds tne interface to get a record from the CRT/ 
Keyboard. 


@ Builds the interface to put a record to the CRT, 


@ Builds the interface to first put a record to the CRT, and 
then to get a record from the Keyboard. 


®@ Builds the interface to use the program function keys. 


The CRT/Keyboard provides information to the CRT/ 
Keyboard data management routines that perform the 
input/output operations. 


Display Support 


The macros which follow support the display functions of 
the CRT/Keyboard. 


Define the File for CRT (SDTFS) 


The $DTFS macro instruction provides information need- 
ed to allocate, open, and access a CRT file. This macro 
instruction generates the code that builds a CRT DTF. 
When using this macro, $DTFO CRT-Y or ALL-Y must 
also be used. See Appendix B: Define the File Control 
Blocks for a description of the CRT DTFs. 


The format of the SDTFS macro instruction is: 


[PUTDAT-address| |,PUTLOC-number} 
{,UP-mask]| {,CHN-address} 


{,PUTLEN-number; {,OPC-code] 
{,GETDAT-address} [,GETLOC-number} 
{,GETLEN-number] UBLANK-Y/N] 





PUTDAT-adadress specifies the leftmost byte of the logical 
record for a put request. For a $PGS request, this area is 
used for the output. If this operand ts not specified, 
X‘0000' is assumed, and the address must be updated with 
{or prior to) the first $°GS or $PUTS request issued. 
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PUTLOC-number specifies a number which represents the 
starting location on the CRT for a put request. Valid 
entries for this operand are from 0 through 278. If this 
operand is not specified, O (the first CRT position) is 
assumed. If the number exceeds 278, no data is written. 


UP-mask specifies the mask to test the eight external 
indicators. The code for the UP-mask must be specified 

as 8 binary bits. For example, to test bits 0, 3, 5, and 7, 
you would enter UP-10010101. The UP-mask is compared 
to the external indicators set on by the SWITCH statement 
for conditionally opening files. If the bits that are on in the 
UP-mask are also on in the external indicators set on by the 
SWITCH statement, the file will be opened. If the UP-mask 
is all zeroes or not used, the file will be unconditionally 
opened. 


Note: |Information on setting external indicators (SWITCH 
statement) can be found in the /BM System/3 Model 15 
System Control Programming Reference Manual (for 
Program Number 5704-SC1), GC21-5077, and in the 
IBM System/3 Model 15 System Control Programming 
Concepts and Reference Manual (for Program Number 
5704-SC2) GC21-5162. 


CHN-name specifies the address of the next DTF in the 
forward DTF chain. !f there isno DTF chain or if this DTF 
is the tast one in the chain, this operand should be omitted 
and end of chain (X‘FFFF’) assumed. 


PUTLEN-number specifies the number of bytes to process 
for a put request. If this operand is not specified, the miss- 
ing information must be supplied with (or prior to) the first 
$PGS or S$PUTS request. 


Valid entries for this operand are from 1 through 279. If 
this number plus the entry for the PUTLOC operand 
exceeds 279, the data written is truncated at location 278. 


OPC-code specifies the operation code to be set. If this 
operand is not specified, the information must be supplied 
with (or prior to issuing) the first $GETS, $PUTS, or $PGS 
request. The codes and their meanings are: 


Code Meaning 

IN Set operation code for input only (SGETS). 

INR Set operation code for input on request 
(SGETS). 

OUT Set operation code for output only 
(SPUTS). 

OUTIN Set operation code for output/input 
(for $PGS). 


GETDAT-address specifies the leftmost byte of the area 
into which the input data will be placed for a get request; 
for a $PGS request, this area is used for the input. {f this 
operand is not specified, X‘0000’ is assumed, and the infor- 
mation must be supplied with (or prior to issuing) the 

first SGETS or $PGS request. 


GETLOC-number specifies a number which indicates the 
starting location on the CRT for a get request. Valid 
entries for this operand are O through 278. If this operand 
is not specified, O (the first CRT position) is assumed. If 
a number greater than 278 is specified, no data will be 
read. 


GETLEN-number is a decimal number which represents the 
number of bytes to get. If this Operand is not specified, 
X‘0000' is assumed, and the missing information must be 
supplied with (or prior to issuing) the first $PGS or $PUTS 
request. Valid entries for this operand are 1 through 279. 
If this number plus the entry specified for the GETLOC 
operand exceeds 279, the data read is truncated after 
location 278. 


BLANK-Y/N determines whether to leave the previous data 
in the CRT buffer or to blank the buffer. If Y (yes) is 
specified, the operation code is set to blank the buffer. If 
this operand is not specified, N (no) is assumed. When 
used in conjunction with the $PUTS and $PGS macros, 

the operand causes all 279 bytes to be blanked; when used 
with $GETS, only the input area is blanked. 


Get a Record from the CRT/Keyboard (GE TS) 


The $GETS macro instruction generates the interface need- 
ed to communicate with CRT data Management when a 
record is being read from the CRT. To use this macro in- 
struction, construct a CRT DTF for the file and use the 
$DTFO macro to establish the offsets for the DTF. You 
must include an EXTRN for $$CODM. If you will need 

to use the data in register 2 at a later time, you should 

save the contents of that register before using the $GETS 
macro instruction. 


The format for the $GETS macro instruction is: 


[Name] | $GETS | [DTF-address] [.,GETDAT-address] 
(,GETLEN-number] [,GETLOC-number] 


U.,BLAN K-Y/N] [,OPC-IN/I NR/N] 
[,EOF-address] 





DTF-address specifies the leftmost byte of the DTF for 
this file. If this operand is not specified, the address of the 
DTF is assumed to be in register 2. 


GETDAT-address specifies the leftmost byte of the area 
into which the data will be placed. 


GETLEN-number specifies the number of bytes to get. 
Valid entries for this operand are 1 through 279. If the 
sum of this number plus the number specified for the 
GETLOC operand exceeds 279, the data read is truncated 
after location 279. 


GETLOC-number specifies a number representing the start- 
ing location on the CRT for this get. Valid entries for this 

operand are O (the first CRT position) through 278. If this 
entry exceeds 278, no data is read. If this operand is omit- 
ted, the corresponding entry in the DTF is not modified. 


BLANK-Y/N determines whether to leave the previous data 
in the CRT buffer or to blank the buffer. If Y (yes) is 
specified, the operation code is set to blank the buffer. If 
this operand is not specified, N (no) is assumed. 


OPC-IN/INR/N determines whether to set the Operation 
code to input only (IN), to input on request (INR), or to 
leave the operation code unchanged. If INR is entered, the 
operator is prompted WAITING FOR REQUEST. Then, 
when the PA1 key is pressed, ENTER DATA is prompted. 
If N (no) is specified or if this operand is omitted, the 
operation code is not changed. 


EOF-address specifies the address in your program that 
should receive control when end of file is recognized (end 
of file is indicated by /* as the first two characters of input) 
If this operand is not specified, no code is generated to 
check for the end-of-file condition, and you should check 
the return code in your program to determine the outcome 
of the operation. 


Generate a PUT/GET Operation Through CRT Data 
Management ($PGS) 


This macro instruction generates a PUT/GET data request 
to CRT data management. To use this instruction, you 
must construct a CRT DTF for the file and use the $DTFO 
macro instruction to establish the offsets in the DTF. 
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You must alse oroviue the labe!s for the necessary data 
management oitines through an EXTRN for $$CODM. 


Mh you will vece (u use the data in register 2 at a later time 
you shuald save the contents of that register before issuing 
the $PGS macro instruction. 














The iariet fur the SPGS macro instruction Is: 
finame! | SPGS [OTF address] |,BLANK-Y/N] [,OPC-Y/N] 
i | PUPDAT-address} [PPUTLEN-number} 
fPUTLOC-number] [,GETDAT-address} 


|,GETILEN-number] |,.GETLOC-number} 
| EQE-address} 


) 
| 
| 
{ 
i 
1 


OFF-address specifies the address of the DTF for this file. 
If the operand is not specified, the address is assumed to 


han redisver Z, 


rt ANK. YON doterraines whether to blank the data in the 
279 byte input area before 4 CRT operation. tf Y (yes) is 
specified, che operation code is set to blank the input area; 
tis operand is omitted, N (no) is assumed and the area 
is not blanked. 





OPC. YAM specttics whether to set the operation code to 
sutput/ingiut TPN is specified or if this operand is not 
specified, N (19) © assumed, and the operation code is not 
modified in the DTF. 


PUTODAT-address identifies the leftmost byte of the user 
area from which the data will be taken. 


PUTLEN-number specifies the number of bytes to put to 
the CRT. Valid entries for this operand are 1 through 279. 
if tne sum of this number plus the entry specified for the 
PUTLOC operand exceeds 279, the data written is truncated 
after location 278. 


PUTLOC-number specifies the starting location on the 
screen for this put request. Valid entries for this operand 
are O (the first CRT position) through 278. If this number 
exceeds 278, no data is written. 


GETDAT-number specifies the leftmost byte of the area 
into which the data will be placed. 


60 






GETLEN-nuinber specifies the number of bytes to get from 
the CRT. Valid entries for this operand are 1 through 279. 
lf the sum of this number plus the entry specified for the 
GETLOC operand exceeds 279, the data read is truncated 
after location 278. 


GETLOC-number specifies the starting location on the CRT 
for this get request. Valid entries for this operand are O 
(the first CRT position) through 278. !f this number 
exceeds 278, no data is read. 


EOF-address specifies the address in your program that 
should receive control when end of file is recognized 
(indicated by the characters /* in the tirst two input posi- 
tions). If this operand is not specified, no code is generated 
to check for the end-of-file condition, and you should 
check the return code in your program for the outcome of 
the operation. 


Note: If the following operands — PUTDAT, PUTLOC, 
PUTLEN, GETDAT, GETLOC, GETLEN, BLANK, or OPC 
— are not specitied, you must supply the missing informa- 
tion in the DTF before issuing the first $PGS request. 


Put a Record to the CRT via Data Management ($PUTS) 


This macro instruction generates a put data request to CRT 
data management. To use this macro instruction, you must 
construct a CRT DTF for the file and use the $DTFO 
macro instruction to establish the offsets in the DTF. 


If you will need to use the data in register 2 at a later time, 
you should save the contents of that register before issuing 
the $PUTS macro instruction. You must also provide the 
labels for the necessary data management routines through 
an EXTRN to $$CODM. 


The format for the $PUTS macro instruction is: 





[DTF-address} [,BLANK-Y/N} [,OPC-Y/N] 
{ PUTDAT-address] [|,PUTLOC-number} 
{ PUTLEN-number ] 





[Name]] $PUTS 





DTF-address specifies the address of the DTF for this file. 
If this operand is not specified, the address is assumed to be 
in register 2. 


BLANK-Y/N specifies whether to blank the data in the 
279-byte input area before a CRT operation. If Y (yes) is 
specified, the operation code is set to blank the input area. 
If this operand is omitted or if N (no) is specified, the input 
area is not blanked. 


OPC-Y/N specifies whether the operation code is set to out- 
put only. If this operand is omitted, or if N (no) is specified, 
the operation code is not modified. 


PUTDAT-address specifies the leftmost byte of the area 
from which the data will be taken. 


PUTLOC-number specifies the starting location on the CRT 
for this put. Valid entries for this operand are O (the first 
CRT position) through 278. If this number exceeds 278, 
no data is written. 


PUTLEN-number specifies how many bytes to put to the 
CRT. Valid entries for this operand are 1 through 279. If 
the sum of this number plus the entry specified for the 
PUTLOC operand exceeds 279, the data written is truncated 
at location 278. 


Note: |f the following operands — PUTDAT, PUTLOC, 
PUTLEN, BLANK, or OPC — are missing, the missing in- 
formation must be supplied in the DTF before the first put 
request is issued. 


Program Function Key Support 


Program Function (PF) keys 1-9 on the CRT/Keyboard are 
available for use in your program. When an assigned PF key 
is pressed, the program requesting its use is notified. The 
program may then test to see which key was pressed in 
order to condition subsequent operations. 


Generate a Parameter List for a Program Function Key 
Request ($CQEP} 


This macro instruction generates a ten-byte parameter list 
which requests a program function key. The format of the 
generated list is as follows: 


Byte Field Description 
0-6 Reserved 

7 COE QO-code 

8 COE request code 
9 PF key requested 


The format of the $CQEP macro instruction is: 


SCOEP 


[KEY-number | 





KE Y-number specifies the number of the program function 
key requested (keys 1-9 are available for assignment to your 
program). If this operand is not specified, PF is assigned. 


Allocate Program Function Key to a Programm (SPF KY} 


The $PFKY macro should be used initially to allocate a 
function key to a program for subsequent testing via the 
SPFKT macro. If the function key has already been 
allocated, the ERR branch will be affected. 


The format of the SPFKY macro instruction is: 


[CQE-address] [,ERR-address} 





CQE-address specifies the address of the pararneter list that 
specifies which program function key to assign, and loads 
this address into register 1. 'f this operand is not specified, 
the address is assumed to be in register 1 (see SCQEP). If 
you will need the contents of register 1 at a later time, you 
should save the contents of that register before issuing the 
$SPFKY macro instruction. 


ERR-address specifies the address in your program that 
shouid receive contro! if the completion cocie in the param- 
eter list indicates that the requested key is not available 

If this operand is not specified, no code is generated to 
check for a successful key assigriment, and you should 
check the completion code in your parameter list to deter- 
mine the outcome of the operation {a value of X‘40° at 
displacement 2 in the parameter fist indicates that a key 
was successfully assigned). 
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Test for Program Function Key Pressed ($PEKT) 


Your program can either wait for a program function key 
to be pressed, or it can test at any time to see if a specified 
key was pressed. Only one program function key can be 
pressed before your program is notified. 


This macro instruction generates code to test whether a 
program function key was pressed. The chart under Using 
More Than One Program Function Key shows the value to 
check for to determine if a specific key was pressed. 


The format of the $PFKT macro instruction is: 


Le 


CQE-address specifies the address of the parameter list that 
was used to request the assignment of the program function 
key being tested, and loads this address into register 1 (the 
address is assumed to be in register 1 if this operand is not 
specified). (f you will need the contents of register 1 at a 
later time, you should save the contents of that register 
before issuing the $PFKT macro instruction. 






{[CQE-address] [,WAIT-Y/N] 
[,LABEL-address] 





WAIT-Y/N specifies whether to wait for the assigned pro- 
gram function key to be pressed. If Y (yes) is specified, 
your program waits until an assigned key is pressed. If no 
keys have been assigned, this is a permanent wait. If N 
(no) is specified, or if this operand is cmitted, the LABEL 
operand must be specified. 
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LABEL-address specifies the address in your program that 
should receive contro! when an assigned program function 
key is pressed. This operand is used only if WAIT-N is 
specified or if the WAIT operand is omitted. 


Using More Than One Program Function Key 


If you want to use more than one program function key in 
your program, you must request each key separately, using 
the SPFK'Y macio instruction. You must use a different 
parameter list for each different key you wish to assign. 


To test if a program tunction key was pressed, you should 


issue the SPFKT macro instruction. Then, when contro! 
is returned to your program, you should determine which 
key was pressed. The following chart shows which fields 

in the parameter list should be modified and investigated: 


Value to set a displacement 
OS before issuing SPFKY 


Value to test for at dis- 
placement 02 after issuing 


PF Key Macro instruction $PFIKY macro instruction 
1 X‘00' X'34" 
2 X‘05' X'32’ 
3 X‘DA' X‘33' 
4 X‘OF’ X'34' 
5 x14" X‘35' 
6 X'S X'36' 
7 X'1E’ X'37' 
3 X'23' X‘38’ 
g X‘28" X‘39' 


OCL FOR MACRO PROCESSOR 


OCL statements used to call the macro processor can be 
entered through the system input device or be called as a 
procedure from the source library. The OCL statements 
necessary to call the macro processor are shown in Figure 
14. The // COMPILE statement shown is only necessary 
when input is in a source library. 


SAMPLE PROGRAM 


This sample program uses the macro processor and the 
IBM System/3 Model 15 Basic Assembler Program: 5704- 
AS1 or 5704-AS2. The coding shown in Figure 15 pro- 
duces an object program. To use the program, you must 
link edit the object program and execute it. The macro 
processor can be used with any valid assembler on the IBM 
System/3 Model 15 and is not limited to use with the 
program product 5704-AS1 or 5704-AS2. 


Purpose of the Sample Program 


The sample program in Figure 15 is used to print input 
records entered from the system input device. It reads 
data records from the system input device and prints them 
on a line printer. Each printed line reproduces one input 
record. If the spooling function is active for this program, 


the input may have been read prior to running this program, 


and the output may be retrieved at any time convenient 
for you. 
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Termination of the Sample Program 
The sample program terminates in one of two ways: 


Ae After successful completion of the program, EJ is 
displayed on the CRT. 


2. When an error occurs during processing, one of the 
following halts is displayed on the CRT. 


A1-—if an error is returned from the system input 
routine, 


A2-—if an error is returned from the printer routine. 


You respond to these halts by choosing option 2. 
EJ is then displayed on the CRT. 
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Figure 14. OCL Statements for Using the Macro Processor 
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Macro Instructions Used in the Sample Program 


Fifteen macro instructions are used in this sample program. 
The macro instructions and their functions are: 


Macro Instruction Function 
$ALOC Allocates the printer file to this program. 
$OPEN Opens the file after allocation. 
$CLOS Closes the output file. 
$DTFD Constructs the DTF for disk. 
$EOJ Calls the end-of-job routine. 
$READ Reads input records from the system reader. 
$PUTP Prints output records on the printer. 
$DTFP Constructs the DTF for the printer. 
$DTFO Establishes the offsets for the printer and disk DTFs. 
$RLSD Generates offsets for the system reader parameter list. 
$RLST Constructs the parameter list for the system reader. 
$LOGD Generates offsets for the system log parameter list. 
$LOG Logs message on the system log device. 
$LMSG Constructs the parameter list for the system log. 
$PUTD Puts records to a disk file. 
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Evror Description 

A keyword response has resulted in an ivalid 
decunal diait or a boundary exceeded condition 
(Seu note) 


AY ctor cit catlidalion exists 1 this macro in 
strcticg. Noenblank characters were found ta 
columns | T3 of the continued Fine. Ai remain 


boa fines of 1iis macro instruction wilt be tlaggect 
me the eri. code “OC’. 
' 


A keyword response resulted ia character string 
Hhatvaceeds the maxinum tength. (See note} 


AY erorim continuation exists in the previous 
fiasro mstucton, Common 72 is blank. All 
renmaiag lies of this macro instruction will be 
Uagged anth the error code ‘OC’ or ‘NE’. 


A debatites is missing or invalid i the operand 
Ol be previous Macro instruction. 


A keyword ia the macre instrbetion beay 


peceossed ts pat valid. 


Aviovelid pararneter has been found in one of 
ie operands Of The previous macro instruchon. 


fhe macro sastraction being processed contains 





whberteni operation code tot contained wm the 
sovece brary of the program pack, 


Poe qmemore Gperation code of the previous 
roacro mmsinicton is invalid. (See codes ‘CE’ and 
i fore possitie catise for tis error code.) 

S hoyword ooxponse bas resulted th an tivalidl 


stibstigig teres. (See note) 


She 





wuld respanse fs resulted tn a substi iiig 


wentax eorur. {See note) 
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Appendix B: Define the File Control Blocks 


The DTF provides information to the data management 
routines about files you use. You must provide one DTF 
for each file you use in a program. Certain fields serve the 
same purpose in all pre-open DTFs. (Pre-open DTFs are 
reformatted to post-open when they are opened by using 
the allocate and open macro instructions.) 


The figures in this appendix describe both the pre-open 
and post-open DTFs for unit record and disk devices. 


Figure DTF Described 
17 MFCU 

18 MFCM 

19 1442 

20 Line Printer 

21 2501 

22 Disk 

23 Tape 

24 Device Independent 
25 CRT/Keyboard 
26 3741 


The labels given to the fields in these figures are the labels 
generated by the offset macro instruction $DTFO. Dis- 
placements are hexadecimal numbers which refer to the 
rightmost byte of the field; length is specified in bytes. 
Addresses in the DTFs point to the leftmost byte of the 
referenced area. 
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$DFDEV Device code 
MFCU1 (primary hopper of MFCU) = X’F0’ 
MFCU2 (secondary hopper of MFCU) = X‘F8’ 


$DFUPS External indicators 

$DFAT1 Attribute byte 1 

Bit On Meaning 
Read 
Print 


Punch 
Card image mode 





$DFAT2 Attribute byte 2 


Bit On Meaning 


Device is system reader 

Multiple buffers 

EOF on multiple buffers 

/. or /& read on last input operation 
DTF has been opened 





$DFCHA Address of next DTF in backward chain 
$DFCHB Address of next DTF in forward chain 
$DFARR Address recall register save area (return address) 
$DFXRS XR1 save area (contents of calling program register 1) 
| SDFLRA Logical record address 
$DFCMP Completion code 
Code Meaning 
X'40’ Successful completion 


xX’41’ Permanent error 
X'42' End of file indicator 








Figure 17 (Part 1 of 2). MFCU DTF 
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Fiowee 17 (Part 20f 2). MECU DTF 
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Field 
Name Displacement Length Contents 


$DFDEV 0 1 Device code 
MFCM1 (primary hopper of MFCM) = X‘FO’ 
MFCM2 (secondary hopper of MFCM) = X‘F8’ 














$DFUPS 1 1 External indicators 
$DFAT1 2 1 Attribute byte 1 
Bit On Meaning 
0 Read 
1 Print 
2 Punch 
3 Card image mode 
4 DTF for MFCM 
5 Interpret mode 
6 Print head 5 or 6 to be used 
$DFAT2 3 1 Attribute byte 2 
Bit On Meaning 
2 Device is system reader 
3 Multiple buffers (data) 
4 EOF on multiple buffers 
5 /. or /& read on last input operation 
7 DTF has been opened 
$DFCHA 5 2 Address of next DTF in backward chain 
$DFCHB 7 2 Address of next DTF in forward chain 
$DFARR 9 2 Address recall register save area (return address) 
$DFXRS B 2 XR1 save area (contents of calling program register 1) 
$DFLRA D 2 Logical record address 
$DFCMP E 1 Completion code 
Code Meaning 
X‘40' Successful completion 
X‘41' Permanent error 
X‘42’ End of file 


Figure 18 (Part 1 of 2). MFCM DTF 
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$DFOPC 





$DFSTS 
$DFCIA 
$SDFRDA 
$DFPNA 
$DFPTA 


$DFNIO 





$DFQ 


$DFR 


$DFRDL 


$SDFPNL 


$DFPTL 


$DFPHS 


$DFIND 


Displacement 





















10 


12 


14 


16 


18 


1A 


1B 


1C 


1D 














Contents 


Operation code 








Bit On Meaning 
0 Read 
1 Print 
2 Punch 
3 Defer operation 
4 Card image 
5 No feed 
6 Four tier printing 
1 Stacker select 
2 |OB 
2 Read I/O area address' 
2 Punch I/O area address! 
2 Print !/O area address! 
1 Number of IOBs! 
1 Q-byte (device address) 
1 R-byte 
1 Read length! 
1 Punch length 
1 Print length 
1 Print head select 





Indicator byte 


Bit On Meaning 
0 Previous operation was print 
it Feed required before print 
2 Read already completed 
3 First-time bit for interpret 


1 Indicates field is used for pre-open DTF. 


Figure 18 (Part 2 of 2). MFCM DTF 
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SDFUPS 


$DFAT1 


$DFAT2 


$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFLRA 


$DFCMP 


$DFOPC 


Figure 19 (Part 1 of 2). 1442 DTF 


Contents 
Device code X‘50’ 
External indicators 
Attribute byte 1 
Bit On Meaning 
0 Read 
2 Punch 
3 Card image mode 
Attribute byte 2 
Bit On Meaning 
Device is system reader 
Multiple buffers (data) 
EOF on multiple buffers 
/. or /& read on last input operation 
DTF has been opened 


Address of next DTF in backward chain 


Address of next DTF in forward chain 


Address recall register save area (return address) 


XR1 save area (contents of calling program register 1) 
Logical record address 
Completion code 
Code Meaning 
X‘40’ Successful completion 
X‘41’ Permanent error 
X‘42’ End of file 
Operation code 
Bit On Meaning 
Read 
Print 
Punch 
Defer operation 


Card image mode 
No feed 
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Displacement 


$DFSTS 10 
$DFCIA 12 
$DFRDA 14 
$DFPNA 16 
$DFNIO 19 
$DFQ 1A 
$DFR 1B 
$DFPNL 1D 


1 Indicates field is used for Pre-open DTF. 
igure 19 (Part 2 of 2). 1442 DTF 
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Contents 

Stacker select (MFCU, MFCM, 1442) 
1OB address’ 

Read 1/O area address! 

Punch 1/O area address! 

Number of 1OBs! 

Q-byte (device address) 

R-byte 


Punch length 
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Field 
Name Dispiacement Length Contents ! 
$DFDEV 0 1 Device code 
Code Meaning 
X‘E0’ 1403 
xX'11' 3284 
SDFUPS 1 1 External indicators 
$DFAT1 Z 1 Attribute byte 1 
Bit On Meaning 
1 Print 
$DFAT2 3 ] Attribute byte 2 
Bit On Meaning 
6 Halt on unprintable character | 
7 DTF has been opened | 
$DFCHA 5 2 Address of next DTF in backward chain 
$DFCHB 7 2 Address of next DTF in forward chain 
$DFARR 9 2 Address recall register save area (return address) 
SDFXRS B 2 XR1 save area (contents of calling program register 1) 
SDFLRA D 2 logical record address 
$DFCMP E 1 Completion code 
Code Meaning 
X40’ Successful completion 
x’AT' Permanent error i 
X'42' End of file 
X'48' Overflow on the printet 
$DFOPC F | | Operation code 
Bit On Meaning 
1 Print | 
$DFSKB 10 1 Line number to skip to before the print operation 
$DFSPB 11 1 Number of lines to space before the print operation 
$DFSKA 12 1 Line number to skip to after the print operation 
$DFSPA 13 1 Number of lines to space after the print operation 
athe ee [a eee S cea 


Figure 20 (Part 1 of 2). Line Printer DTF 
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Displacement 


$DFPQ 


$DFPR 


$DFPIB 


SDFPIO 


$DFPRL 


$DFOVF 


$DFLP 


$DFPOS 


$DFMSK 








$DFPGS 


‘Indicates field is used for pre-open DTF. 


Figure 20 (Part 2 of 2). Line Printer DTF 


76 


Contents 

Q-byte (device address) 
R-byte 

1OB address! 

1/O area address! 
Record length 


Overflow line number! 


Lines per page! 


Position counter 
Maximum skip value! 


Page size save area 





Field 

















Name Displacement Length te Contents 
$DFDEV 0 1 Device code X‘38' 
$DFUPS 1 1 External indicators 
$DFAT1 2 1 Attribute byte 1 
Bit On Meaning 
0 Read 
3 Card image mode 
$DFAT2 3 1 Attribute byte 2 
Bit On Meaning 
2 Device is system reader 
3 Multiple buffers are being used 
4 End-of-file on multiple buffers 
6 /. or /& was read 
7 DTF has been opened 
$DFCHA 5 2 Address of next DTF in backward chain 
$DFCHB 7 2 Address of next DTF in forward chain 
$DFARR 9 2 Address recall register save area (return address) 
$DFXRS B 2 XR1 save area (contents of calling program register 1) 
$DFLRA D 2 Logical record address 
$DFCMP E 1 Completion code 
Code Meaning 
X‘40' Successful completion 
xX'4y' Permanent error 
X'42' End of file 
$DFOPC F 1 Operation code 


Figure 21 (Part 1 of 2). 2501 DTF 








Bit On Meaning 
0 Read 
3 Defer operation 
4 Card image mode 
5 No feed 


Define the File Control Block 
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Displacement Contents 








$DFCIA 12 {OB address! 
S$DFRDA 14 Read 1/O area address! 


$DFNIO 19 Number of IOBs! 


$DFQ 1A O-byte (device address) 





$DFR 1B R-byte 


$DFRDL 1C Read length 





' Indicates field is used for pre-open DTF. 


Figure 21 (Part 2 of 2). 2501 DTF 
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Field 
Name Displacement Length Contents 


$DFDEV Device code:? 

R1 (removable disk — 5444, drive 1) = X‘A0’ 
F1 (fixed disk -- 5444, drive 1) = X’A8’ 

R2 (removable disk — 5444, drive 2) = X‘BO’ 
F2 (fixed disk — 5444, drive 2) = X‘B8’ 

D1 (5445, drive 1) = X‘CO’ 

D2 (5445, drive 2) = X’C8’ 

D3 (5445, drive 3) = X‘DO’ 

D4 (5445, drive 4) = X’D8’ 


















$DFUPS External indicators! 


$DFATi 





Attribute byte 1! 





Bit On Meaning 


Indexed 
Consecutive 
Direct 
Multivolume 
Input 
Output 
Update 

Add 














NOOO WN —- OO 





$DFAT2 Attribute byte 2! 


Bit On Meaning 



















3 Multiple buffers 
7 DTF has been opened 





$DFCHA 





DTF chain pointer A (backward) 





$DFCHB DTF chain pointer B (forward) 








$DFARR 





ARR save area (return address) 





$DFXRS XR1 save area (contents of object program XR1) 


Address of logical record (shared !/O address of logical input record)! 





$DFLRA 





1 Indicates field is used for pre-open DTF. 
| ' Figure 22 (Part 1 of 7). Disk DTF (5704-SC1 only) 
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Displacement Contents 


$DFCMP Completion code 


Code Meaning 


X‘40’ Normal completion 

X'41' Controlled cancel taken on permanent !/O error 
X'42’ End of file (input) 

X'44’ No record found (out of extent for direct files) 
X‘50' Key field does not match key in update record 
X‘60' Duplicate key on attempted load or add 

X‘62’ Keys out of sequence (attempted toad or add) 
X‘64' Key low for this volume or high for any volume 
X‘68’ Key low for this volume 

X‘70' End of extent or end of read (output) 

X'72’ Key high for last volume 


Completion codes other than X‘40’ are returned before the data manage- 
ment function is actually completed. 


$DFOPC Operation Code: 
Bit(s) On Meaning 


Get 
Put/add or put/load 
Put/update 

0,3 Set new limits 


$DFIOB Pre-open address of 1/O area! 
Post open address of IOB 


$DFPRB Address of current process 1OB (dual !/O only; shared 
1/O—address of logical output record). 


$SDFBKL Block length (length of data buffer)! 





$DFRCL Logical record length’ 

$DFPTR Data block index (address of next record) 
$DFRO1 Reserved 

$DFXTA Data start extent 


$DFMVF Address of direct MVF extent table! 


$DFRO2 Reserved 





‘Indicates field is used for pre-open DTF. 
| Figure 22 (Part 2 of 7). Disk DTF (5704-SC1 only) 


Field 
Name Displacement Length Contents 


$DFXTB 






Data end extent (disk address) 








$DFNUM Number of extents (direct MVF)! 


$DFSWA 





Scheduler work area format—1 label sequence number 





$DFNAM 







File name! 





$DFAT3 Attribute byte 3! 


Bit On Meaning 


Addrout 
Ordered load 

Random 

Limits 

End of limits — call to open 

Force end of volume — call to close 
Online multivolume 

Reserved 













NOP WN CO 


$DFAT4 Attribute byte 4! 





Bit On Meaning 

















0 Compiler access method 
1-7 Reserved 








$DFATS Attribute byte 5 (Bits 0-7 are reserved)! 





$DFSEC 





Number of sectors to write (split) 





$DFWAA 





Work area A (disk) 








$DFWAB 





Work area B (disk) 





$DFWAC 





Work area C (disk) 





$DFWAD 





Work area D (disk) 







$DFRO4 Reserved 





$DFRMA Work area, length of first part of overlap record 







$DFRO6 Reserved 








$DF RMB Work area, length of second part of overlap record 





' Indicates field is used for pre-open DTF. 


| Figure 22 (Part 3 of 7). Disk DTF (5704-SC1 only) 
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ene eee Sistas a 
Field 
Name | Displacement Length Contents 
Estes sire Re ne pete APN eS ae ee 
SDFND1 39 1 Indicator byte 1 
Bit On Meaning 
0-3 Reserved 
4 Pseudo-get 
5 High key loaded (indexed output — MVF) 
6 Low key was found 
| 7 Buffer has been written 
$DFIND2 3A 1 Indicator byte 2 
Bit On Meaning 
0 Indexed random update — first time indicator 
1 First record on new volume 
2 MVF end of file 
3 End of all MVF files 
4 Empty file (skip initial index search) 
5 Previous operation was add 
6 End of file has been reached 
7 EOF on this get (limits not set) 
$DFND3 38 1 Indicator byte 3 
Bit On Meaning 
0 Index contains adds or new entries 
1-3 Reserved 
4 Records added 
5 Out of sequence add (key sort needed) 
6 Current process buffer contains adds 
7 Current process buffer contains updates 
$DFRO7 3C 1 Reserved 
$DF RO8 3D 1 Reserved area 1 (5444 only) 
$DFNXR 41 4 Disk address of next record (CSDD) 
$DFSPC 42 1 Nurnber of tracks in cylinder 
$DF ROO 43 1 Reserved 
$DFIOA 46 3 Disk address save area 
$DFDAT 48 2 Pointer to current index entry. 
obo eee il 





a 











End of Disk DTF for consecutive output 





Figure 22 (Part 4 of 7). Disk DTF (5704-SC1 only) 
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Fieid 












SDFR10 


SDFR1I 1 Reserved area | byte (5444 only) 


$S$DFEOF 3 Disk address of logical end of file (CSD) 


End of Disk DTF for consecutive input and update 


SDENXK | 4D (3) Disk address of logical end of index (CSD) 
$DFKPR 4F ? Pointer written index (pointer to next buffer entry) 
SDFKAD 51 2 Address of user’s key area‘ 


SDFKCR 53 2 Address of key in core (direct) 


End of Disk DTF for direct 





































‘ tndicates field is used for pre-open DTF. 


| Figure 22 (Part 5 of 7), Disk DTF (5704-SC1 oniy) 


Define : 


SpFCU R 7 i: ae ee Y pideeeas Saas key (index) Oo - 
$DFHI 53 (2) Address of high key (limits) 

S$DFR12 54 1 Reserved 

SDFKXA 56 2 Start extent of index (disk address of first track} 
$DF KBF 58 2 Address of index Tt 

SDFKL | 5A 2 Key length! 

SDF R13 5B Reserved 

SOFKXB 5E 3 Disk address of end of index (CSD) 

SDFKD 60 2 Displacement of bey in record! 

$DFBL.X 61 1 Index black size! 

$DFRI4 | 62 | Reserved 

SDFFILX 64 9 | Disk address of statt of index (6445) 

$DFR15 65 1 Ais A eee 


re ba nora Block 


eer on he ORLA NT NN 


Displacement Length Contents 
49 ! Reserved 





Field 
Name Displacement Length Contents 





$DFDTX 67 2 Start of disk track index (5445) disk address 
$DFABF 69 Address of add index |OB 


$DFAPR 6B 2 Add index buffer pointer 





End of Disk DTF for index sequential input output, and update 





$DFMIX 6D 2 Address of in-core index (random)! 


$DFLOW 6F 2 Address of low key (limit) 





End of Disk DTF for input or update with limits 





$DFLST 6F (2) Address of last key (indexed sequential) 
$DFHAD 71 Address of high add key bucket! 
$DFLOT 71 Address of save area for current key! 
$DFHPK 73 Address of high primary key 

$DFBYT 75 2 Number of bytes in in-core index! 

End of Disk DTF for index random input and update 

$DFAPT Pointer to next record in add buffer 
$DFR16 Reserved 

$DFR17 Reserved area 1 byte (5444 only) 


$DFKXP Disk address of end of primary index 





$DFSLP Save area for last index disk pointer 
$DFR18 Reserved 
$DFSLA Save area for last index disk address 


End of Disk DTF for index sequential add and update add 





’ Indicates field is used for pre-open DTF. 


| Figure 22 (Part 6 of 7). Disk DTF (5704-SC1 only) 


B4 


Displacement Contents 


$DFSTA Multivolume file table pointer 


SDFSEO Volume sequence number of current volume 
$DFNXT Volume sequence number of next volume 
$DFF1S Start of format-1 

$DFF1 Format-1 save area 

$DFARi EOV save area 

$DFXR1 EOV save area 

$DFKEY Address of high key from Format-7 


$DFTAB Address of multivolume information table 





$DFENT Number of entries in in-core index 








$DFVOL Number of volumes online 





End of Disk DTF for multivolume file processing 


| Figure 22 (Part 7 of 7). Disk DTF (5704-SC1 only) 
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Field 








Name Displacement Length 
So treat tein Loa I ee ss went aa nate 4 Sos Rete es 
SDFDEV | a 1 
4 
| 
| 
| | 
i | 
| 
| j 
$DFUPS 1 1 
SDFAT1 | 2 1 
{ 
| 
| | 
Pepearg | 3 1 
| t 
' | f 
: | 
| 
| 
| | 
SDECI 5 | 2 


t 


‘Tncicates Geb use tur ore-open DF 


Figure 22a (Part i of 7% 
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+++ 


| 


! 





stamens ee natn a ne i ae geen net at i tenn Rana 


Contents 
Device code:! 
R1 (simulation area, drive 1) = X’AO’ 
F1 (simulation area, drive 1) = X’A8’ 
R2 (simulation area, drive 2) = X‘BO’ 
F2 (simulation area, drive 2) = X'B8’ 
D1 (3340 drive 1) = X’CO’ 
D2 (3340 drive 2) = X’C8" 
D3/D31 (3340 drive 3) = X‘DO' or 
(3344 drive 3, logical unit 1) = X’DO’ 
04/D41 (3340 drive 4) = X’D8’ or 
(3344 drive 4, logical unit 1) = X’D8’ 
032 (3344 drive 3, logical unit 2) = X’D1' 


N33 (3344 drive 3, logical unit 3) = X’D2’ 
034 (3344 drive 3, logical unit 4) = X’D3’ 
= X'D9’ 


043 (3344 drive 4, logical unit 3) = X‘DA’ 


) 
) 
D42 (3344 drive 4, logical unit 2) 
) 
144 (3344 drive 4, logical unit 4) = X‘DB’ 


External indicators’ 


Attribute byte 1? 


Bit On Meaning 
0 Indexed 
1 Consecutive 
2 Uyrect 
3 Multivoluire 
4 fiput 
5 Output 
6 Update 
7 Add 

Atiribute byte 2} 

Bit On Meaning 
0 Device independent DTF 
i OTF allocated 
2 Device is SYSIN 
3 Multipie buffers data 
4 Deterred open 
5 EOV -- Close ignored bit 
6 EOV - - Call close 
/ Opened 


DTF chain poirmer A (backward) 





tok OFF (2704-SC2 ontyi 


Page of GC21-7608-2 
Issued 29 September 1978 
By TNL: GN21-5649 





Field 
Name Dispiacement Length Contents 
| oa eeSe. , nes San, _ = 
SDFCHB 7 2 DTF chain pointer B (forward)! 
$DFARR 9 2 | ARR save area (return address) 
$DFXRS B 2 | XR1 save area (contents of object program XR1) 
| 
$DFLRA D 2 Address of logical record (shared I/O address of logical input record)! 
$DFCMP E 1 | Completion code: 
Code Meaning 
( X ‘00’ Record not found (requested key low) 
| X'40' Successful completion 
x'41' Permanent error 
X'42' End of file 
X'44' No record found 
X'50’ Update key not equal to key 
X‘60' Duplicate key on load or add 
X'62' Keys out of sequence on load or add 
| X64’ Key low for this volume or high for any volume 
X'68’ Key low for this volume 
X’70' End of extent or end of reel 
X’72' Key high for last volume 
Completion codes other than X’40’ are returned before the data man- 
agement function is actually completed. 
$DFOPC F 1 Operation code: 
| Bit(s) On Meaning 
X'30' Get 
X'40' Put/update 
X’60' Put/add or put/load 
X'90’ Set new limits 
SDFIOB 1 2 Pre-open address of !/O area! 
Post open address of IOB 
i 
$DFPRB | 13 2 Address of current process 1OB (dual 1/O only; shared 
1/O — address of logical output record). 
$DFBKL 15 2 Block length (length of data buffer)! 
| 
$DFRCL 17 2 | Logical record length* 
SDFPTR i 19 2 i Data block index (address of next record) 








' Indicates field used for pre-open DTF. 





Figure 22a {Part 2 of 7). Disk DTF (5704-SC2 only) 
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Page of GC21-7608-2 
Issued 29 September 1978 
By TNL: GN21-5649 







































pet Te the 
Displacement Length 
7 ——— 
$DFSEG 1A | 1 File snare segment number 
| : 
$DFXTA 1C 2 O-sx address of start of data 
$DFMVF 1c (2) | Address of direct MVF extent table! 
$DFQOB iD j Device-:ndependent O code 
$DFXTB 1F 2 Doss address of end of data 
$DFNUM 1F (2) Number of extents (direct MVF}! 
{ 
| | SDFSWA 20 | 1 Scneauler work area tormat-1 label sequence number 
$DFNAM 28 8 Foe name’ 
$DFAT3 29 1 Attibute byte 3!: 
Bit On Meaning 
0 Addrout 
1 Ordered load 
i 2 Random 
3 Limits 
4 End of limits — call to open 
5 Force end of volume — call to close 
G Online multivolume 
| : Reserved 
$DFAT4 2A 1 Att .bute byte 4: 
Bit On Meaning 
9 Compiler access method 
1 Bypass direct file clear 
| z 3340s supported 
: 3 No verify (main data area) 
4-6 Reserved 
| 7 Consecutive add from start of file 
$DFAT5 2B 1 | Attribute byte 5!: 
: Bit On Meaning 
| 0 Format-1 for this DTF 
i 1 Fite share 
| 2 Copying a PTAM file 
3 External buffers 
4 External buffers closed 
5 Multivoiume file share support 
6 CCP task 
7 Reserved 





a 





' Indicates field used for pre-open DTF. 
Figure 22a (Part 3 of 7). Disk DTF (5704-SC2 only) 
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Page of GC21-7608-2 
Issued 29 September 1978 
By TNL: GN21-5649 











Displacement Length UL Contents 
$DFSEC 2C 1 Number of sectors to write ispi:t) 
$DFWAA 2D 1 Work area A (disk) 
f 
i 
i 
$DFWAB 2E 1 Work area B (disk) 
$DFWAC 2F 1 | Work area C (disk) 
$DFWAD 30 1 Work area D (disk) 
$DFRO4 31 1 | Reserved 
| 
$DFROG 32 1 | Reserved 
i 
i 
$DFRMA 35 3 | Work area, length of first part of overtap record 
| 
| 
$DFRMB 38 3 | Work area, length of second part of overlap record 
| 
| 
$DFND1 39 1 | Indicator byte 1: 
Bit On Meaning 
0 Buffer is resuit of scan-read 
1 Switch butters or pointers in subroutine 
2 Update porcers to share DTF 
| 3 Partially flied add buffer written 
4 Pseudo-gét 
5 High key 'caded {indexed output — MVF) 
| 6 Low key was found 
7 Buffer has peen written 
$DFND2 3A 1 | Indicator byte 2: 
Bit On Meaning 
{ 
i 0 Indexed random update - first time indicator 
1 First recovs on new veiume 
| 2 MVF end xf fie 
' 3 End of ae Mvt files 
| 4 Empty fils: (skip initial «ndex search) 
5 Previous 3oe-aton was add 
6 End of file as beer reached 
7 EOF on thes get (iimiis not set) 
$DFND3 3B 1 | Indicator byte 3: 
i i Bit On Meaning 
0 Current process butfer contains update 
| 1 Added entries in input index buffer 
2 Records in add buffer were updated 
3 End of data in input buffer — indexed 
4 Records added 
| 5 Out of sequence add ‘(key sort needed) 
6 Current process buffer contains adds 
7 New entries in add index buffer 














' Indicates field is used for Pre-open DTF. 
Figure 22a (Part 4 of 7). Disk DTF (5704-SC2 only} 
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Page of GC21-7608-2 
Issued 29 September 1978 
By TNL: GN21-5649 

















Field 
Name Displacement Length Contents 
$DFWAE 3C 1 Work area E (disk) 
! 
$DFPUN 3D 1 Physical unit simulation area only 
$DFNXR 41 4 Disk address of next record (CSDD) 
$DFSHR 43 2 Address of file share DTF 
| 
$DFIOA 46 3 | Disk address save area 
$DFDAT 48 2 Pointer to current index entry 
$DFND5 49 1 Indicator byte 5 
Code Meaning 
0 Get has not been done 
1 Do not flush buffers in close 
2-7 Reserved 
$DFR11 4A 1 Reserved (simulation area only) 





End of Disk DTF for consecutive output 


$DFEOF 4D 3 Disk address of logical end of file (CSD) 


End of Disk DTF for consecutive input and update 











$DFNXK 4D (3) | Disk siacet logical end of index (CSD) 
$DFKPR 4F 2 Pointer written index (pointer to next buffer entry) 
$DFKAD 51 2 Address of user’s key area! 
$DFKCR 53 2 Address of key in core (direct) 

I 





End of Disk DTF for direct 


$DFCUR 53 (2) Address of current key (index) 

$DFHI 53 (2) Address of high key (limits) 

$DFR12 54 1 Reserved 

$DFKXA 56 2 Start extent of index (disk address of first track) 
$DFKBF 58 2 Address of index lOB 





1 Indicates field is used for pre-open DTF. 
Figure 22a (Part 5 of 7). Disk DTF (5704-SC2 only) 
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Field 














Name Displacement Length Contents 
Bile. 
$SDFKL 5A 2 Key length! 
$DFND4 5B 1 Indicator byte 4 
Code Meaning 

0 First key invalid in index buffer 

1 First add buffer not filled 

2 Add area already formatted 

3-7 Reserved 
$DFKXB 5E 3 Disk address of end of index (CSD) 
$DFKD 60 2 Displacement of key in record! 
SDFBLX 61 1 Index block size? 
$DFR14 62 1 Reserved 
$DFR15 63 1 Reserved 
$DFFLX 65 2 Disk address of start of index (main data area) 
$DFDTX 67 2 Start of disk track index disk address (main data area) 
$DFABF 69 2 Address of add index 1|OB 
$DFAPR 6B 2 Add index buffer pointer 


End of Disk DTF for index sequential input output, and update 





$DFMIX 


$DFLOW 


6D 2 Address of in-core index (random)! 


6F 


2 Address of low key (limit) 





End of Disk DTF for input or 


update with limits 





$DFLST 
$DFHAD 
SDFHPK 


$DFBYT 


6F 


71 


73 


75 





[ (2) Address of last key (indexed sequential) 
2 Address of high add key bucket! 
2 Address of high primary key 
2 Number of bytes in in-core index! 


lh 


End of Disk DTF for index random input and update 


‘ Indicates field is used for pre-open DTF. 


Figure 22a (Part 6 of 7). Disk DTF (5704-SC2 only) 


Define the File Contro!] Block 91 









Field 












Name Displacement Length Contents 

$DFAPT 77 2 Pointer to next record in add buffer 
$DFR16 78 1 Reserved 

$DFR17 79 1 Reserved area (simulation area only) 
SDFKXP 7C | 3 Disk address of end of primary index 





End of Disk DTF for index random add, retrieve add, and update add 





T 

















$DFSLP 7E 2 Save area for last index disk pointer 
$DFR18 7F 1 Reserved 
$DFSLA 82 3 Save area for last index disk address 
End of Disk aE for index sequential add and update add 

| $DFSTA 84 2 | Multivolume file table pointer 
SDFSEQ 85 1 Volume sequence number of current volume 
SDFNXT 86 1 Volume sequence number of next volume 
$DFF1S 87 1 Start of format-1 
SDFF1 C6 63 Format-1 save area 
$DFAR1 C8 2 EQOV save area 
$DFXRI1 CA 2 EOV save area 
$DFKEY cc 2 Address of high key from Format-7 
SDFTAB CE 2 Address of multivolume information table 
$DFENT DO 2 Number of entries in in-core index 
$DFVOL D1 | 1 Number of volumes online 











End of Disk DTF for multivolume file processing 


=igure 22a (Part 7 of 7). Disk DTF (5704-SC2 only) 
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eo ee 


$DFDEV 


$DFUPS 


$DFATI 


$DFAT2 


$DFCHA 
$DFCHB 
$DFARR 
$DFXRS 
$DFLRA 


$DFCMP 


Figure 23 (Part 1 of 4). Tape DTF 


Contents 
Device code: 
T1 (tape unit 1) = X’60’ 
T2 (tape unit 2) = X‘68’ 
T3 (tape unit 3) = X‘70’ 
T4 (tape unit 4) = X‘78’ 
External indicators 
Attribute byte 1 
Bit On Meaning 
Consecutive 
Direct 
Output 
Attribute byte 2 


Bit On Meaning 


Multiple buffers (data) 
OTF has been opened 


Address of next DTF in backward chain 
Address of next DTF in forward chain 


Address recall register save area (return address) 


XR1 save area (contents of calling program register 1) 


Logical record address 
Completion code 
Code Meaning 


X‘40’ Successful completion 

X'41' Permanent error 

X'45’ Skip a bad input block 

X‘70' End of extent or end of reel 

X‘90' Wrong length record on input — short 
X‘91' Wrong length record on input — long 
X‘FO’ Option 0 to error message 

X'F 1’ Option 1 to error message 


Define the File Control Block 
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Field 
Name 


$DFOPC 


$DFIOB 


$DFPRB 


$DFLIO 


$DFBKL 


$DFRCL 


$DFPTR 


$DFCRL 


$DFBCT 


$DFRO3 


$DFSWA 


$DFNAM 




















Displacement Length | Contents 
F | Operation code 

Code Meaning 
X‘04' Read forward 
X‘06' Read backward 
X‘08' Write 
X‘0A’ Write tape mark 
X’0OB’ Rewind 
X‘0C’ Backspace file 
X‘OD’ Rewind and unload 
X‘OE’ Forward space file 
X'1C’ Backspace block 
X‘TE’ Forward space block 
X’40' Variable length 
X‘80’ Fixed length 

11 2 Pre-open address of I/O area! 

Post-open address of |OB 

13 2 Address of process 1OB 

13 (2) Length of I/O area! 

15 2 Block length! 

17 2 Record length! 

19 2 Pointer to logical record in buffer 

1B 2 Current record length 

1D 2 Block count 

1F 2 Reserved 

20 1 Scheduler work area format—1 index number 

28 8 File name! 


' Indicates field is used for pre-open DTF. 


Figure 23 (Part 2 of 4). Tape DTF 
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Field 
Name 








Displacement Length Contents 





$DFAT3 29 1 


Bit On 











NOmPpPWN- CO 


$DFAT4 





Attribute byte 4 


Bit On 





$DFATS 





$SDFHTC Error halt cade 





Code 


X'10' 
X11 
x‘12' 
X‘20' 
X'21' 
X‘40' 
xX‘41' 
X‘50' 
X‘60’ 
X61’ 
X'62' 
X'70° 

















Figure 23 (Part 3 of 4). Tape DTF 


Attribute byte 3 


Bits 0-5 are record format bits 


Attribute byte 5 (Bits 0-7 are reserved) 








Meaning 





Fixed length 
Variable length 

Unblocked records 

Blocked records 

Spanned records 

ASCII format D. 

ASCII data management present (pre-open) 
ASCII file (post-open) 





Meaning 


Rewind at close 
Unload at close 
Leave at close 
Basic access method 
Standard label tape 
Locate mode 






















No multivolume output 
[37 F closed by EOV 
Reel opened on this fue 


Meaning 


No get operation code 

Wrong length record on input 
Wrong length block 

No put operation code 

Wrong length record on output 
Permanent tape write error at close 
Wrong block count 

Permanent tape read error at close 
No file statement 

File not allocated 

Not enough buffer space 

No basic operation code 
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$DFSOU 


$DFOST 


$DFWRA 
$DFWRB 
$DFWRC 
$DFWRD 
$DFRO5 


$DFND1 


$DFND2 
$DFHSA 
$DFSR1 

$DFSVD 


$DFSVE 


Figure 23 (Part 4 of 4). Tape DTF 
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Contents 
Format—1 sequence number 
ASCII buffer offset byte 
Code Meaning 
X‘80' Offset is 4 bytes for block length 
X‘00’ No offset specified 
Bits 1-7 are reserved for offsets of 0-99. 
Work area A 
Work area B 
Work area C 
Work area D 
Reserved 
Indicator byte 1 
Bit On Meaning 
!0B not waited on 
Truncated block 
Empty variable block 
Error reading trailer label 
Write trailer label 
DTF closed by EOV 


EOV return via open 
No end of file reached 


NO OP WN - OO 


Indicator byte 2 (bits 0-7 are reserved) 
Halt routine save area 

EOV register 1 save area 

EOV chain DTF address save area 


EOV save area 





Field 
Name Displacement Length Contents 




































$DFDEV Device code X’40’ 
$DFUPS 1 External indicators 
$DFAT1 1 Attribute byte 1 
Bit On Meaning 

0 Indexed 

1 Consecutive 

2 Direct 

3 Multivolume 

4 Input 

5 Output 

6 Update 

7 Add 
$DFAT2 1 Attribute byte 2 

Bit On Meaning 

0 Device independent DTF 

3 Multiple buffers (data) 

5 /& read on last input operation 

7 DTF has been opened 
$DFCHA 2 Address of next DTF in backward chain 
$DFCHB 2 Address of next DTF in forward chain 
$DFARR 2 Address recall register save area (return address) 
$DFXRS 2 XR1 save area (contents of calling program register 1) 
$DFLRA 2 Logical record address 
$DFCMP 1 Completion code 


Code Meaning 


x‘40’ Successful completion 
X‘41" Permanent error 
X'42’ End of file 


End of extent or end of reel 





X‘70' 





Figure 24 (Part 1 of 5). Device Independent DTF 
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Field 
Name Displacement Length Contents 

















$DFOPC F 1 Operation code 
Bit On Meaning 

0 Get 

1 Put 
$DFIOB 11 2 Pre-open address of !/O area! 

Post-open address of |OB 
$DFPRB 13 2 Address of process 1|OB 
$DFBKL 15 2 Block length! 
$DFRCL 17 2 Record length? 
$DFPTR 19 2 Pointer to logical record in buffer 
$DFPOV 1A 1 Printer overflow 
$DFRO1 1A (1) Reserved 
$DFXTA 1c 2 Disk address of start of data 
$DFOB 1D 1 Q-byte (device address) 
$DFRO2 1D (1) Reserved 
$DFBCT 1D (1) Block count 
$DFXTB 1F 2 Disk address of end of data 
$DFSWA 20 1 Scheduler work area format—1 index number 
$DFNAM 28 8 File name! 
$DFAT3 29 1 Attribute byte 3 
Bits 0-5 are record format bits 
Bit On Meaning 

0 Fixed length 

1 Not used 

2 Unblocked records 

3 Blocked records 

4 Spanned records 

5 ASCII format D 

6 ASCII data management present (pre-open) 

- ASCII file (post-open) 


' Indicates field is used for pre-open DTF. 
Figure 24 (Part 2 of 5). Device Independent DTF 
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Field 
Name 


$DFAT4 


Displacement Length Contents 


2A 1 Attribute byte 4 














Bit On Meaning 









oO 
= 


NOOB WN > OY. 


Rewind at close 

Unload at close 

Leave at close 

Basic access method 
Standard label tape 
Locate mode 

No multivolume output 
DTF closed by EOV 
Reel opened on this file 








$DFATS 2B 1 Attribute byte 5 (Bits 0-7 are reserved) 








$DFHTC 2C 1 Error halt code 






Code Meaning 









X‘10’ No get operation code 






















x11’ Wrong length record on input 
X12’ Wrong length block 

X‘20' No put operation code 

X'21' Wrong length record on output 
X‘'40’ Permanent tape write error at close 
X'41’ Wrong block count 

X‘50’ Permanent tape read error at close 
X‘60’ No file statement 

X'61’ File not allocated 

X'62' Not enough buffer space 

X‘70’ No basic operation code 









$DFSEC 2C (1) Number of sectors to write (split) 










S$DFWAA 2D 1 Work area A (disk) 










$DFSQU 2D (1) Format—1 sequence number (tape) 









$DFWAB 2E 1 Work area B (disk) 













$DFWAC 2F 1 Work area C (disk) 













$DFWAD 30 1 Work area D (disk) 










$DFRO4 31 1 Reserved 









$SDFRMA 34 3 Work area (disk) 






Figure 24 (Part 3 of 5). Device Independent DTF 
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Field 
Name Displacement Length 
35 1 


$DFRO6 





Reserved 








$DFRMB 38 Work area (disk) 


$DFND1 





Indicator byte 1 


Bit On 


NOOR WDNH - CO 





$DFND2 Indicator byte 2 


Bit On 















Wn oO 


4,5 


Qo 





$DFND3 Indicator byte 3 





Bit On 


0-3 
4 
5-7 











$DFRO7 Reserved 


$DFHSA 





$DF RO8 





$DFSR1 





$DFSVD 














$DFNXR 





Figure 24 (Part 4 of 5). Device Independent DTF 
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Halt routine save area 


Reserved area 1 byte (5444 only) 


EOV register 1 save area 


EOV chain DTF address save area 


Disk address of next record 














Meaning 


{OB not waited on 
Truncated block 
Empty variable block 
Error reading trailer label 
Write trailer label 
DTF closed by EOV 
EOV return via open 
No end of file reached 










Meaning 


Device=5444 Disk 
Device=5445 Disk 
Device=Tape 
Device=MFCM 
Reserved 

1OB waited on indicator 
Write indicator 





Meaning 


















Reserved 
Short record on unit record device 
Reserved 











Displacement Contents 





$DFSPC 43 Number of tracks in cylinder 
$DFSVE 43 EOV save area 
$DFRO9 44 Reserved 


$DFIOA 47 Disk address save area 


$DFDAT 49 Pointer to current index entry buffer pointer save 
area (split) 


$DFR10 Reserved 


$DFR11 Reserved area minus 1 byte (5444 only) 








$DFEOF Disk address of logical end of file 


$DFDVI Reserved for independent DTF 





Figure 24 (Part 5 of 5). Device Independent DTF 
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Field 
Name Displacement 


$DFDEV 
$DFUPS 


$DFAT1 


$DFAT2 


$DFCHA 
$DFCHB 
S$DFARR 
$DFXRS 


SDFLRA 





$DFCMP 


Figure 25 (Part 1 of 2). CRT/Keyboard DTF 


102 


Contents 


Device code X‘10' 


External indicators 


Attribute byte 1 
Not used 


Attribute byte 2 
Bit On Meaning 

Device independent DTF 
DTF has been allocated 
Device is system input device 
Multiple buffers (if this bit is off, it indicates 
the first entry to CRT data management) 
DTF has been opened 

Address of the next DTF in backward chain 


Address of next DTF in forward chain 


Address recall register save area (return address) 


XR1 save area (contents of calling program register 1) 


Logical record address 
Completion code 
Code Meaning 
X’40’ Successful completion 


x‘41' Permanent error 
X'42' End of file indicator 





Operation code 








Field 
Name Displacement Length 
F 1 


$DFOPC 










Bit On Meaning 






None 





No operation 













0 Input only 
0,1 Output/Input, Put/Get 
0,3 Input on request 
0,1,2,3 Clear zone portion of OPC 
1 Output only 
5 Do not blank buffer before operation 
4,5,6,7 Clear numeric portion of OPC 








$DFCLB 






Length of data, output 





$DFCSB 







Start position, output 





$DFCRA 







Address of data, input 







$DFCLI Length of data, input 





$DFCSI 






Start position of input 






$DFCOE Console queue element (CQE) 






$DFECB Console queue element ECB 






$DFQCB Console queue element Q-code 







$DFREQ Console queue element request code 





$DFADR Address of DTF 


Figure 25 (Part 2 of 2). CRT/Keyboard DTF 
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pee: spelt 


0 1 Device code:! 
3741 = X‘40’ 
























$DFDEV 


External indicators! 





$DFUPS 





$DFAT1 Attribute byte 1! 


Bit On Meaning 
Consecutive 


4 Input 
Output 


$DFAT2 Attribute byte 2! 








Bit On Meaning 
Device independent 
Allocated 

System input 
Multiple buffers 
DTF has been opened 











NWN OO 


$DFCHA DTF chain pointer A (backward) 











$DFCHB DTF chain pointer B (forward)? 


$DFARR ARR save area (return address} 





$DFXRS 







XR1 save area (contents of object program XR1) 








$DFLRA Address of logical record! 













$DFCMP Completion code 


Code Meaning 


X‘40' Normal completion 
X'41’ Controlled cancel taken on permanent !/O error 
X'42' End of file (input) 


' Indicates field is used for pre-open DTF. 
Figure 26 (Part 1 of 2). 3741 DTF 
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$DFOPC 













$DFIOB 










$DFPRB 


$DFBKL 


$DFRCL 





$DFPTR 





$DFRO1 


$DFXTA 





SDFMVF 





$DFRO2 





$DFXTB 






$DFNUM 






$DFSWA 







$DFNAM 





' Indicates field is used for pre-open DTF. 
Figure 26 (Part 2 of 2). 3741 DTF 


Field 
Name Displacement | Length Contents 





Completion codes other than X’40’ are returned before the data manage- 
ment function is actually completed. 


Operation Code: 





Bit(s) On Meaning 





0 
1 


Get 
Put 









Pre-open address of 1/O area! 
Post-open address of |OB 


Address of current process {OB 





Block length (length of data buffer)! 







Logical record length? 







Reserved 













Reserved 


Reserved 


Reserved 


Reserved 


Reserved 


Reserved 


Reserved 





File name? 
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Appendix C: input/Output Blocks 


DISK INPUT/OUTPUT BLOCK 


You build the disk |OB by issuing the $1OBD macro 
instruction. If you use $RDD, $WRTD, or $SWAIT in your 
program, you must use the $1OED macro instruction to 
assign the offset in the 1OB. The format of the 1OB and 
the labels assigned to the fields are shown in Figure 27. 
IOBs for the 5444 Disk Storage Drive, the 5445 Disk 
Storage, the 3340 Direct Access Storage Facility, and 

the 3344 Direct Access Storage are 30 bytes long. 
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Contents 





mmon equates for all devices 


a [ Dispiacement Length 


soon 

SIBECK 0 Wait/post byte ~- byte 1 of three-byte ECB 

SIBCOM 1 Completion code - byte 2 of ECB. 

SIBCMP 2 1 The third byte of ECB. A one-byte completion code indicating the status 
of the operation just performed. You should check this byte before 
assuming that the data transfer has occurred. Before the wait routine 1s 
called, each bit in this byte has the following meaning: 

| Bit On Meaning 
| 0 Seek has been started on the operation requested 


by the LOB. 

The operation requested is complete 

Data transfer is pending on this operation. 

Data transfer has been started on this operation. 
A wait occurs for this 1|OB 


OBwWwnhn = 


If bit 7 is also on, there is an error on an associated 
1OB; it bit 7 is off, a scan equal has been found. 
i 


aS 


The scan is not satisfied. 
A permanent error has occurred on this {OB or an 





~w 


associated 1OB. 


After the wait routine has finished, the code in this byte has the 
following meaning: 


| 
| 
| 








Code Meaning 
X'40' Successful completion 
X'41' Permanent I/O error. 
| X‘42' Scan sot satisfied. 
X'44' Scan equal found. 
i X'45' Permanent error on an associated IOB. 
SIBCHN 6 4 Address of the next 1OB in tiie chain. 1OBs are chained only when the 


{ 

| file requires more than oie 1OB. This area ly always present, even when 
| chaining is not used. When the operation specified by this [OB is 

complete, this area contains the disk address last used (cylinder/secior 





for the 5444; head/record for the 5445). 
ROE : 7 1 The C-byte of the start 1/O(SIO) command. You set this byte through 
the SIOBD macro imistruction. 
SIBR ts 3 1 | The R-byte of the start 1/O commeiid. It further defines the operaticn 
| requested. Figure 28 shows the possible R-byte settings for the SIO 
{ command. 
et eschew a a eee 


Figure 2? (Par: Toft 4). Disk 1OB Format 
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Label 


Displacement Contents 











S$IBEID 9 





ERP module displacement ID. 










$IBDAT B 2 Address of the leftmost byte of your data area. You provide this address 


Through the $IOBD macro instruction. 






$IBSNS D 2 The area used by the input/output supervisor to contain device status 
sense information. The contents of this area are described in Figure 29. 






$IBFLG E 1 Indicates special handling required for I/O operations through the various 
bit settings. You set bits O and 4 through the $IOBD macro instruction. 
If no special handling is required this byte must be set to X‘00’. The 

bit settings are: 









Bit On Meaning 






0 No recovery is to be attempted is a data check, missing 
address mark, no record found, or track condition 
check error condition occurs. 
















1 No verification is to be done on write operations. 

2 No error logging is to be done if any disk {/O error 
should occur. Control is to be returned to the calling 
routine. 

3 Disk 1OS should not use the C and S bytes in the 10B, 






but should pick up the F, C, and S bytes at the end of 
the IOB for use in this operation. This bit should be 
used only by the system control program. 
























4 The calling routine is not using disk data management; 
therefore, this 1OB is not associated with a DTF. 

5 There is no load I/O of the disk file data register 
(DFDR). 

6 Error logging is in progress. 

7 A data transfer operation involving an alternate track is 
in progress. 









$IBERR F 1 The area used by disk 1OS to count the number of retries required to 


complete the I/O request. 
















SIBTCB 





Task control block (TCB) address. 








SIBWRK 10S partial completion code. 






Figure 27 (Part 2 of 4). Disk 1OB Format 
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Contents 


$IBFL2 Flag byte for use with the 5445. The meanings of the bits are: 


Bit On Meaning 


0 Special seek 
1 Super !1OB 
2 Not used (5704-SC1) 
Specify operation (5704-SC2) 
where: X‘11' Scan 
X'10'~—s- Write 
X’01' Read 
X'00’ Seek 
Not used (5704-SC1) 
Reserved 
Not used (5704-SC1) 
C/S address must be converted but not Q-byte 
(5704-SC2) 
No seek 
Long form IOB 





The hexadecimal value of the cylinder address where the operation 
is to begin (5445 only). 
You set this byte through the $IOBD macro instruction. 





The hexadecimal value of the head address where the operation is to 
begin (5445 only). 
You set this byte through the $1OBD macro instruction. 


The hexadecimal value of the cylinder address where the operation 
is to begin (5444 only). 
You set this byte through the $1OBD macro instruction. 


The hexadecimal value of the record address where the operation 
is to begin (5445 only). 
You set this byte through the $1OBD macro instruction. 





The hexadecimal value of the beginning sector address of the 
operation (5444 only). 
You set this byte through the $1OBD macro instruction. 





The number of records minus one, in hexadecimal, involved in the 
data transfer (5445). 
You set this byte through the $1OBD macro instruction. 


The number of sectors minus one, in hexadecimal, involved in the 
data transfer (5444). 
You set this byte through the $1OBD macro instruction. 











Figure 27 (Part 3 of 4). Disk 1OB Format 
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Label Bnolacanent. al “eantanis 7 se en ee 
SIBDAD 19 Pointe: to 5445 ten-byte disk address. 
$!BDCH 1B The disk data management chain pointer (5444 and 5445). Ht contains 
the address of the second of the two JOBs used for double buffering 
$IBDTF 1D 


The address of the DTF associated with this 1OB 











Figure 27 (Part 4 of 4). Disk 1OB Format 
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1/0 
Operation 


S10 R-Byte 
Settings (Hex) 


5444 Settings 


Interpretation 

















Controi | 60 Seek 
O0 Data 
Read Oo identifier 
| 02 Diagnostic 
3 i Verify 
i: ae + : pee 
Write 00 ! Data 
61 Identifier 
eat ~ sb alias ia ae  pisiedadtat ne gets 
ao Equal 
Scan oY Low or equal 


5445 Settings 


High or equal 


























oe + 4 
Control 00 i Seek 
i o1 | Recalibrate 
=e. ofa eee bie tr : at 
Read ! 00 ; Key-data 
OS | Verify key-data 
Write 00 Key-data 
\ Ba N tara ad es Spa ba oe 2 = 
60 Key-data equal 
Sean 01 ! Key-data low or equai 
02 Key-data hign or equal 
ran 


Figure 28. R-Byte Settings 


TIMER INPUT/OUTPUT BLOCK 


if you use the $SIT, STOD, or SRIT macro instructions in 
your program, you must build the timer 1OB by issuing the 
$TIOB macro instruction. The format of the timer [OB 
varies depending on whether DATE-Y or DATE-N is speci- 
fied. 


Format of Timer [OB When DATE-Y is Specified 


Bytes Contents 
1 Reserved 
2-7 Time 
8-13 Date 


Format of Timer 1|OB When DATE-N is Specified 


Bytes Contents 

1 Reserved 

2-7 Time 

8 Return Code 
9-10 Reserved 


input/Output Blocks 
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Device 


Byte 





5444 


5445 











Bit On 


“OOR WN OO NOOR WN HO 


WON SLwnrn- 0 


indication 


1/0 no-op (single only) 
Intervention required 
Missing address mark 
Equipment check 
Data check 

No record found 
Track condition check 
Seek check 

Scan equa! 

Access arm at cylinder 0 
End of cylinder 

Seek busy 

Hundred cylinders 
Device overrun 

Status address A* 
Status address B* 


Format error 
Intervention required 
Missing address mark 
Equipment check 
Data check 

No record found 
No-op 

Overrun 





NOOPWNH - 





Disk drive error 

Unsafe 

Seek 1 complete 

Seek 2 complete 

Data operation complete 

End of cylinder has been reached 
Scan equal 

Disk drive ID** 


*tndicates which drive on the 5444 had last data transfer: 


Rits 6-7 00—Drive 1 
01--Drive 2 
** Bit 7 0.-Drive 1 
1—Drive 2 


Figure 29. Device Status Sense information 
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Appendix D: Macro Instruction Summary Chart 


Figure 30 is a summary chart containing all valid macro 
processor instructions. The macro instructions are listed 
in alphabetical order. In addition to the name, three items 
are given for each macro instruction: 

@ Format of the instruction with all valid operands 

@ Function of the macro instruction 


@ Maximum number of statements generated 


For more detailed information on any of the macro 
instructions, see Chapter 2: Macro Instruction Statements. 


Macro Instruction Summary Chart 412.1 
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112.2 


Name of Macro Instruction 


[Name] | SCHK 


[Name] 


[Name] 


{Name] 


[Name} 


[Name] 


[Name] 


$CKL 


SCLOS 
$COMN 
$CQEP 


[CKL-address] 


DTF-address[,SKIP-Y/N] [,REQK-Y/N] 
LRTN-Y/N] [,LAST-Y/N] 





[DTF-address] 


[KEY-number] 


c | | | 


$CTLT | [DTF-address] {,OPC-code} 


[Name] | $DATE 


$DTFC 


$DTFD 


| LABEL-address] 


(OBA-address, N1OB-number 
{[,DEV-code] 

[,UP-mask] [,CHN-address] 
{,RCAD-address] [,OPC-code] 
[|,DEFER-Y/N] [,CARDI-Y/N] 
LPRINT4-Y/N] [,FEED-Y/N] 
LSTACKR-number] [,READA-address] 
{,PUNCHA-address] [,PRINTA-address ] 
{,READL-number] [,PUNCHL-number] 
{,PRINTL-number] [,PRHEAD-mask]} 
LALIGN-Y/N] 





AC-code,RECL-number,NAME-filename, 
BLKL-number,|O-address 

| ,DISK-5444/5445/3340] 

[,UP-mask] [,BUFNO-1/2] L.MVF-N/Y] 
[,LIM-N/Y] [,ORD-N/Y] [,BIN-N/Y] 
[,CHN-address] {,RCAD-address] 


[,ENT-number] |,MVFN-number! 
[,KEYL-number] [,KEYD-number] 
[,KEYA-address] [,MVFT-address] 
{,MSTX-address] [,1BLKL-number] 
tL. ADKEY-address] [,EOVK-address] 
(.SHR-Y/N] [,EXTBUF-Y/N} 





Figure 30 (Part 1 of 6). Macro instruction Summary Chart 
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Function 


Assigns the file indicated by the DTF to your 
program. 


Tests for 1/O operation completion in the 
check list. 


Generates an entry for the check list to be 
used by the check routine. 


Prepares the device for job termination. 


Generates equates. 


Generates a parameter list for a program func- 
tion key request. 


{ssues control commands to the tape device. 


Retrieves system date. 


Builds a DTF for a card file. 


Builds a DTF for a disk file. 


The SHR-Y/N and EXTBUF-Y/N 
Parameters apply only to Program Number 
5704-SC2. 


Macro Instruction Summary Chart 


Maximum Num- 
ber of Statements 
Generated 


8 


None 


11 


33 


210 


113 
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Name of Macro tnstruction 





NAME-filename,RECL-number,|O-address 
L,AC-IN/OUT] [,BLKL-number] 
L.RCAD-address] [,BUFNO-1/2] 
[,CHN-address] [,UP-mask] 
















NAME -filename,RECL-number,|O-address 
L,AC-1/O] [,RCAD-address] [,BUFNO-1/2] 
[,CHN-address] [,UP-mask] 


[DISK-Y/N] [,TAPE-Y/N] [,IND-Y/NI | 


[.MFCU-Y/N] {,MFCM-Y/N] {,03741-Y/N] 
[,02501-Y/N] [,D1442-Y/N] [,D1403-Y/N] 
(,03284-Y/N] [,CRT-Y/N] [,ALL-Y/N] 

| FIELD-Y/N] 


| [Name] ] $DTFP | RCAD address,1OBA-address, |OAA-address, 
OVFL-number ,PAGE-number [,DEV-code] 
[,UP-mask] [HUC-Y/N] [,CHN-address] 
LPRINT-Y/N] [,SKIPB-number] 
[,SPACEB-number] [,SKIPA-number} 
{,SPACEA-number] [,RECL-number] 


[Name] 
























[PUTDAT-address] [,PUTLOC-number] 
[,UP-mask] [,CHN-address]} 
[,PUTLEN-number] [,OPC-code] 
{.,GETDAT-address! [,GETLOC-number] 
[,GETLEN-number] [,BLANK-Y/N] 








NAME -filename,tO-address,BLK L-number, 
RECL-number [,UP-mask] [,AC-IN/OUT] 
[,CHN-address] [,BASIC-Y/N] 

|,RCAD-address] [,MODE-LOCATE/MOVE} 
L.MBUFF-Y/N] [,RECFM-ccde] 

[,LIOA-number] [,SPAN-Y/N] [,CODE-A/E] 
[,OSET-B/number] [,END-code} [,MVF-Y/N] 


| [Name ]| $EOJ | [CANCEL-NORMAL/IMMED/CONTRL] | 
[Name] | $FIND | NAME-module {,FIND-address] ipack.e/s]| 
| | (Name} | SFTCH [_ Name modu name[,PACK-P/S] | 


| Figure 30 (Part 2 of 6). Macro Instruction Summary Chart 
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Function 


Builds a DTF for a device independent file. 


Builds a DTF for a 3741 file. 


Establishes labels for fields on a DTF. 


Builds a DTF for a printer file. 


Builds a DTF for a CRT file. 


Builds a DTF for a tape file. 


Terminates the job and returns control to the 
supervisor. 


Provides the disk address of a module in the 
O tibrary. 


Finds and loads an O module and passes 
control to it. 


Maximum Num- 
ber of Statements 
Generated 


838 


16 


None 


33 


37 


67 


23 


21 
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Name of Macro Instruction Function Maximum Num- 


ber of Statements 





Generated 
[DEV-code] [,DTF-address] [,EOF-address] Gets a record from a card file. at 
[,ERR-address] {,OPC-Y/N} 
[,READL-number |] |,CARDI-Y/N} 
[, STACKR-number] 
{AC-code] \ Gets a record from a disk file via disk data 46 
[EBAC-code]} | management. 
(,DTF-address] [,ERR-address] 
{,EOF-address] [,NFR-address] The EBAC-code parameter applies only to 
{ LSTV-address] [ NOK Y-address] Program Number 5704-SC2. 
[Name] {[DTF-address] [,RCAD-address] Gets a record from a device independent file. 32 


{,ERR-address] [,EOF-address] 


$GETK| EOF-address {,DTF-address] [,ERR-address} Gets a record from a 3741 file. 


{Name] | $GETS | [DTF-address] {,GETDAT-address} Gets a record from the CRT keyboard. 48 
[,GETLEN-number]} [,GETLOC-number } 
L.BLANK-Y/N] [,OPC-IN/INR/N] 
{,EOF-address] 





[Name] |} $GETT | MODULE-name[,DTF-adaress | Gets a record froma tape file. 35 
|,RCAD-address] [,OPC-Y/N] 
[,ERR-address} [,EOF-address] 


{Name} | $GPC ([DEV-code! [,DTF-address] [,OPC-code] Constructs a get, then a put interface to 37 
,»DEFER-Y/N} [,CARDI-Y/N] a card file. 

/WPRINT4-Y/N] {,FEED-Y/N} 

STACKR-number! |,READL-number| 

/PUNCHL-number] |,PRINTL-number| 

/PRHEAD-mask] [,EOF-address] 

,ERR-address | 





[Name] | $1O0BD DISK-5444/5445/3340} [,CYL-number]} Builds an (OB for a disk file. 40 
SCTR-number!} [,HEAD-number | 

#NUM-number] {,BUFF-address} 

,O-number | |,ERREC-IOS/USER} 

,LOG-Y/N} |,VER-Y/N} {,CHN-address] 





Establishes labels for fields tn the disk 1OB. None 
{Name} | $LMSG | [FORMAT-code} |,COMP-code! Generates log list for halt message. Linkage 12 
[,HALT-code] [,SUBH-code| |,SEV-code] to jog may also be generated. 


[,DEF-code} [,OPNO-Y/N] [,OPN1-Y/N] 
[,OPN2-Y/N} [,OPN3-Y/N] [TLEN-number | 
{, TADR-address | 
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Name of Macro tnstruction 





{Name] 











[Name] 


[Name] 


[Name] ] $PFKY COE-address] [,ERR-address] 


{Name} 


[Name] 


LOAD] FIND-address [,LOAD-2/address] 


pt 


$LOAD | NAME-module name [,FIND-address] 







{,LOAD-2/address} LUSE-R/NR} 
[,PLIST-address] [,PACK-P/S] 





[.PACK-P/S] 


{LIST-address] [|,OPNO-address] 
[,OPN1-address} [,OPN2-address] 


$LWTO] TLEN-number, TADR-address {,COMP-code | 


$PFKT 


$PGS 


$PUTC 


(,HALT-code] [,SUBH-code] [,REPLY-Y/N] 
(,RLEN-numberj [,RADR-address] 





[DT F-address] 


{CQE-address]} LWAIT-Y/N ] 
,LABEL-address] 





DTF-address] L.BLANK-Y/N] [,OPC-Y/N] 
/PUTDAT-address] [,PUTLEN-number | 
{,PUTLOC-number} [,GETDAT-address| 
,GETLEN-number] {,GETLOC-number] 
,EOF-address | 


DEV-codej [,DTF-address] [{,OPC-code] 
,DEFER-Y/N] [,PRINT4-Y/N] 
/“FEED-Y/N] [,STACKR-number ] 
[,PUNCHL-number] [,PRINTL-number| 
/PRHEAD-mask} [,ERR-address] 











[EBAC-+ode] 


[Name] | $PUTD toes 


[,DTF-address} [,ERR-address] 
{,EOX-address] [,DUP-address] 
[,SERR-address} [,KERR-address] 
[,UPD-Y/N] [,LSTV-address] 
[,NOKY-address] [,HKER-address] 








[Name] 


$PUTI 


(,DTF-address} [,RCAD-address] 
{,ERR-address] {,EOX-address] 
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Function 


Finds and loads or loads a previously found O 
module into main storage. 


Generates linkage to system log. 


Generates offsets for log lists. 


Generates parameter list for write to operator 
or write to operator with reply function. 


Prepares a previously allocated file for data 
transfer. 


Tests whether a program function key that 
was allocated by $PFKY has been pressed. 


Request allocation of a program function 
key. 


PUT/GET operation through CRT data 
management. 


Puts a record to a card file. 


Writes a record on a disk file via disk data 
management. 


The EBAC-code parameter applies only to 
Program Number 5704-SC2. 


Puts a record to a device independent 
file. 


Maximum Num- 
ber of Statements 
Generated 


4} 


29 


None 


14 


22 


66 


30 


67 


32 


Name of Macro Instruction 





[Inamei] SPUTK| [DTF-address] [,ERR-address] 


[DEV-codel [,DTF-address] LPRINT-Y/N]} 
[,SKIPB-number] [,SPACEB-number} 


[,SKIPA-number] [,SPACEA-number j 
{,ERR-address} [,OVFL-address] 













{Name ] 





|DTF-address} [,BLANK-Y/N] [,OPC-Y/N] 
[|,PUTDAT-address] [,PUTLOC-number] 
{, PUTLEN-number] 


{Name ] 


{[Name]l} $RDD 


MODULE-name [,DTF-address] 
|,RCAD-address] [,OPC-Y/N] 
{,LENAD-address}] {,ERR-address] 


|OB-address,CS-address, NSECT-number 
[,DISK-5444/5445/3340) 


[DTF-address] [,RCAD-address] 
[,DIRECT-FORW/BACK] 


|LIST-address] [,OPC-code} |,EOF-address} 
{,EOJ-address] {,ERR-address] 


[Name| [IOB-name] [,CANCEL-Y/N]| 





SRLSD 


[Name] | $RLST | BUF 1-address, WORK-address{,BUF2-address] 


[Name] | $ROLL } [INDEX-1/2} 
[ iNarne [ ssrr 
| | ,ITYPE-REAL/WAIT/TASK] 


| {Name] | $SNAP | ID-hex,START-address,END-addres 
T 
[iname) $tloB | [DATE-Y/N] 


| Figure 30 (Part 5 of 6}. Macro Instruction Summary Chart 








[1OB-name] (, TYPE-DEC/BIN/TU/TOD] 


PL 








qu 
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Function 


Puts a record to a 3741. 


Prints a record via printer data management. 


Puts a record to the CRT via data management. 


Puts a record to a tape file. 


Reads a record from a disk file via the input/ 
output supervisor. 


Reads a record froma tape file via basic 
tape data management. 


Generates linkage to system reader. 


Returns the amount of time remaining ina 
time interval. 


Generates offsets in system reader parameter 
list. 


Generates system reader parameter list, 
buffers, and work area. 


Generates linkage to rojlout/rollin. This 
macro applies only to Program Number 
5704-SC1. 


Sets a time interval. 


Prints the specified area of main storage on 
the system logging device. 


Generates a timer IOB. 


Maximum Num- 
ber of Statements 


Generated 


37 


38 


33 


19 


21 


32 


None 


17 
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Name of Macro instruction 


{Name} ] $TOD 


[1OB-name] [,REF-Y/N] 
LTYPE-DEC/BIN/TU] 





{[Name}} $TRAN] [TRL-address] 


TO-address,F ROM-address,LEN-number, 
TRT-address 


[Name] [(CODE-E/A] [,HEX-hex] 
[Name] [1OB-label} [,ERR-address] 


{[Name]} $WRTD !OB-address,CS-address, NSECT-number 
[ ,DISK-5444/5445/3340] 





[Name]| $WRTT| [DTF-address] [,RCAD-address] 
[,OPC-Y/N] 


[Name]] $WTT (DTF-address} [,ERR-address] 
[,EOF-address] [,EOT-address] 


(.WLRS-address] [,WLRL.-address] 


[Name]} $XCTL NAME-module name [,LOAD-2/address] 
[,PACK-P/S] 


| Figure 30 (Part 6 of 6). Macro Instruction Summary Chart 
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Function 


Returns the time of day and the system date 
to the program. 


Translates a record using the system translate 
routine. 


Builds a parameter fist to pass information to 
the system translate routine, 


Generates an EBCDIC to ASCII or an ASCII 
to EBCDIC translate table. 


Waits for completion of a disk input/output 
operation. 


Writes a record on a disk file via the input/ 
Output supervisor. 


Writes a record to a tape file via the basic 
tape data management. 


Waits for completion of a basic tape data 
management I/O operation. 


Finds and loads a module at a specified 
address and passes control to it. 


Maximum Num- 
ber of Statements 
Generated 


258 


21 


43 


22 


$ALOC (allocate space) macro instruction 23 
$CHK (check I/O completion) macro instruction 26 
$CKL (generate checklist} macro instruction 25 
$CLOS (prepare device for termination) macro instruction 26 
$COMN (common equates) macro instruction 27 
$COEP (generate parameter list program function key) macro 
instruction 61 
$CTLT (control command for tape) macro instruction 54 
$DATE (obtain system date) macro instruction 19 
$DTFC (card DTF) macro instruction 28 
$DTFD (disk DTF) macro instruction 36 
$DTFI (device-independent DTF) macro instruction 56 
$DTFK (3741 DTF) macro instruction 48 
$DTFO (generate DTF offsets) macro instruction 27 
$DTFP (printer DTF) macro instruction 33 
$DTFS (CRT DTF) macro instruction 58 
$DTFT (tape DTF) macro instruction 49 
$EQOJ (end-of-job} macro instruction 20 
$FIND (find directory entry) macro instruction 13 
$F TCH (load module pass control) macro instruction 16 
$GETC (card get interface) macro instruction 30 
$GETD (disk get interface) macro instruction 40 
$GETI (device-independent get interface) 
macro instruction 57 
$GETK (3741 get interface) macro instruction 48 
$GETS (get record from CRT/keyboard macro instruction 59 
$GETT (tape get interface) macro instruction 52 
$GPC (interface reading, punching and printing 
cards) macro instruction 32 
$iOBD (input/output block disk) macro instruction 45 
$IOED (input/output block offsets) macro instruction 46 
$LMSG (parameter list message system log) 
macro instruction 11 
$LOAD (load module) macro instruction 13 
$LOG (linkage system log) macro instruction 12 
$LOGD (displacements system log) macro 
instruction 12 
$LWTO (parameter list WTO or WTOR) macro 
instruction 10 
$OPEN (prepare an I/O device) macro instruction 24 
$PFKT (test program function key pressed) macro 
instruction 62 
SPFKY (allocate program function key to program) 
macro instruction 61 
$PGS (put/get operation CRT data management) macro 
instruction 59 
$PUTC (card put interface) macro instruction 31 
$PUTD (disk put interface) macro instruction 44 
$PUTI (device-independent put interface) macro 
instruction 57 
$PUTK (3741 put interface) macro instruction 49 


Index 


$PUTP (printer put interface) macro instruction 34 

$PUTS (put record CRT data management) macro 
instruction 60 

$PUTT (tape put interface) macro instruction 53 

$RDD (read from disk) macro instruction 46 

$RDT (read from tape) macro instruction 53 

$READ (linkage system reader function) macro 
instruction 9 

$RIT (return interval time) macro instruction 20 

$RLSD (system reader parameter tist offsets) macro 
instruction 8 

$RLST (system reader parameter) macro instruction 8 

$ROLL (rollout/roilin linkage) macro instruction 12 

$SIT (set interval timer) macro instruction 19 

$SNAP (snap dump main storage) macro instruction 18 

$SOURCE file 2 

$TIOB (timer 1OB) macro instruction 19 

$TOD (return time and date) macro instruction 20 

$TRAN (interface translate routine) macro instruction 18 

$TRL (translate parameter list) macro instruction 17 

$TRTB (translate table) macro instruction 18 

SWAIT (wait disk IDS completion) macro instruction 47 

$WRTD (write to disk) macro instruction 47 

$WRTT (write to tape) macro instruction 54 

$WTT {wait tape 1/O completion) macro instruction 55 

$XCTL (load module exchange control) macro 
instruction 17 


access method 40 

allocate program function key to a program ($PFKY) 61 
allocate space (6ALOC) 23 

areas, simulation 35 


block 

disk input/output 106 

input output 106 

timer input/output 111 
block for disk ($IOBD), input/output 45 
block offsets (${OED), input/output 46 
buffer storage requirements 


disk 37 
tape 51 
buffers 


double card device 29 

formatted 24 

initialized 24 

single card device 29 
byte settings, RR 111 


Index 119 


card ($DTFC), file for 28 
card device support 28 
card get interface ($GETC) 30 
card put interface ($PUTC} 31 
cards (SGPC), printing, Punching, and reading interface 32 
chaining 

allocate space routine 23 

close routine 27 

DTFs 23 

open routine 24 
chart, summary, instruction, macro 112 
check for 1/O completion ($CHK) 26 
check routine operation 26 
checklist ($6CKL) 25 
close routine 

input 26 

output 26 
codes, macro instruction error 67 
coding conventions 1 
command for tape ($CTLT), control 54 
comments 3 
COMMON equates ($COMN) 27 
completion ($CHK), check for 1/O 26 
completion ($SWAIT), wait for disk IOS 47 
completion ($WTT), wait for tape 1/O 55 
configuration, minimum system 4 
considerations, Programming 7 
construct a card get interface (SGETC) 30 
construct a card put interface ($PUTC) 31 
construct a device independent get interface ($GETI) 57 
construct a device independent put interface ($PUTI) 57 
construct a disk get interface ($GETD) 40 
construct a disk put interface ($PUTD) 41 
construct a printer put interface ($SPUTP) 34 
construct a tape get interface ($GETT) 52 
construct a tape put interface ($PUTT) 53 
construct a 3741 get interface ($GETK) 48 
construct a 3741 put interface (SPUTK) 49 
construct an interface for reading, punching, and 

Printing cards ($GPC) 32 

continuation coding 3 
contro! ($F TCH), load a module and pass 16 
control ($XCTL), load a module and exchange 17 
control blocks, file 68 
control command for tape ($CTLT) 54 
CRT ($DTFS), file 58 
CRT data management ($PGS), put get operation 59 
CRT support 58 
CRT via data management ($PUTS), put a record 60 
CRT/keyboard 58 
CRT/keyboard ($GETS), get arecord 59 
CRT/keyboard DTF 102 
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data areas, main 35 
data management ($PGS), put get operation 
through CRT 59 
data management ($PUTS), put CRT record 60 
data management interface (tape basic) 
control 54 
read 53 
write 54 
data management routines 
card 30, 31 
CRT/keyboard 59, 60 
device independent 57 
disk 40, 41 
Printer 34 
tape 52,53 
data transfer, input/output file 24 
date ($DATE), obtain system 19 
date ($TOD), return time and 20 
date-N is specified, timer !OB 111 
date-Y is specified, timer 10B 111 
default value, definition 1 
define the file 
card ($DTFC) 28 
CRT ($DTFS) 58 
device independent ($OTFI) 56 
disk (SDTFD) 36 
file sharing 39 
multivolume 52 
printer (SDTFP) 33 
tape ($DTFT) 49 
3741 ($DTFK) 48 
define the file control blocks 68 
deleting macro instructions 4 
device ($OPEN), prepare 1/O 24 
device independent DTF 97 
device independent get interface ($GETI) 57 
device allocation 24 
device independent ($DTFI), file 56 
device independent put interface ($PUTI) 57 
device independent support 56 
device support 
card 28 
CRT/keyboard 58 
device-independent 56 
disk 35 
general 22 
printer 33 
tape 49 
3741 48 
device termination ($CLOS), prepare 26 
devices supported 4 
devices, input and output 4 
directory entry ($FIND), find 13 
disk (SDTFD), file 36 
disk ($1OBD), input/output block 45 
disk ($RDD), read 46 
disk (SWRTD), write 47 
disk buffer storage requirements 37 
disk data management interface, updating a record 41 
disk data management modules, list 42,43 


disk device support 35 
disk DTF (5704-SC1 only) 79 
disk DTF (5704-SC2 only) 86 
disk get interface (SGETD) 40 
disk input/output block 106 
disk input/output supervisor interface 45 
disk }OB format 107 
disk LOS completion ($WAIT), wait 47 
disk put interface ($PUTD) 44 
disk routines 
get 40 
put 41 
read 46 
wait 47 
write 47 
disk, update 41 
displacements for system tog (SLOGD) 12 
display support 58 
DTF 
card 28 
CRT/keyboard 58 
device-independent 56 
disk 36 
printer 33 
tape 49 
DTF defined 
field contents 27 
field lengths 27 
labels 27 
offsets 27 
post-open 24 
pre-open 24 
DTF descriptions 
CRT/keyboard 102 
device-independent 97 
disk (5704-SC1 only) 79 
disk (56704-SC2 only) 86 
general 68 
line printer 75 
MFCM 71 
MFCU 69 
tape 93 
1442 73 
2501 77 
3741 104 
OTF 
chaining 23 
checklist 25 
dump main storage ($SNAP), snap 18 


end-of-job (SEOF) 20 
entry ($FIND), find directory 13 


equates 
generate 27 
labels 8 


system reader parameter list 8 
equates (SCOMN), COMMON) 27 
error codes, macro instruction 67 
error information 67 
exchange control ($SCTL), load module and 17 


file control blocks, define 68 
file, define (see define the file) 
find (form |), load = 13 
find a directory entry ($FIND) 13 
find parameter list after load execution 15 
find parameter list description 14 
format of timer 1OB 
DATE-N specified 111 
DATE-Y specified 111 
format, disk 1|OB 107 
function ($READ), linkage to system reader 9 
function key pressed ($PFKT), test for program 62 
function key request ($COEP), parameter list for program 61 
function key support, program 61 
function key to a program ($PFKY), allocate program 61 


general 1/O support 22 
general SCP support 12 
generate a checklist ($CKL) 25 
generate a parameter list 
message on system log ($LMSG) 11 
program function key request ($CQEP) 61 
WTO or WTOR ($LWTO) 10 
generate a put/get operation through CRT data management 
{$PGS) 59 
generate a system reader parameter list ($RLST) 8 
generate a translate parameter list ($TRL) 17 
generate a translate table ($TRTB) 18 
generate an interface to the translate routine (STRAN) 18 
generate displacements for system log ($LOGD) 12 
generate OTF offsets ($DTFO) 27 
generate equates 27 
generate program function key request 61 
generate the linkage to the system tog ($LOG) 12 
generate timer |OB ($TIOB) 19 
get 
card 30 
CRT/keyboard 59 
device-independent 57 


disk 40 
tape 52 
3741 48 


get a record from the CRT/keyboard ($GETS) 59 
get input operation through CRT data management ($PGS) 59 


halt/systog routine 23 


Index 121 


1/0 completion ($CHK}, check 26 
1/0 completion ($WTT), wait for tape 55 
1/0 device ($OPEN), Prepare 24 
1/O support, general 22 
information, error 67 
input devices supported 4 
input/output block 
disk 106 
timer 111 
input/output block for disk ($IOBD) 45 
input/output block offsets ($IOED) 46 
input/output blocks 106 
input/output supervisor interface (disk) 
read 46 
wait 47 
write 47 
input/output support 22 
input 
close routine 26 
open routine 24 
instructions 
delete macro 4 
macro 4 
macro (list of) 5 
writing macro 1 


interface 
card get 30 
card put 31 


device independent get 57 

device independent put 57 

disk get 40 

disk put 41 

Printer put 34 

reading, punching, and printing cards 32 
tape get 52 


tape put 53 
translate routine 18 
3741 get 48 
3741 put 49 


interrupt program 12 
interval time ($RIT), return 20 
interval timer ($SIT), set 19 
1OB 

formatted 24 

Printer 33 

tape 50 

timer, build 19 

description 111 

format 111 
|OB, disk 

build 45 

description 106 

storage requirements 37 
10S (input/output supervisor) routines 

read 46 

write 47 


122 


jobend 20 
job termination, device 26 


key pressed, test for program function 62 

key request, parameter list for program function 61 
key support, program function 61 

key to program, allocate program function 61 
keywords 1 


label restrictions 
duplicate labels 12 
use of $symbol 7 
warning 27 
labels 
disk 1OBs 46 
equates 8 
line printer DTF 75 
linkage to the system log 12 
linkage to system reader function (SREAD) 9 
linkage, rollout/rollin (GROLL). 2 
list 
description 
find parameter 14 
load parameter 16 
Parameter 
find after load execution 15 
message on system log 11 
program function key request 61 
system reader offsets 8 
translate 17 
WTO orWTOR_ 10 
system reader parameter 8 
load a module and exchange control ($XCTL) 17 
load a module and pass contro! ($F TCH) 16 
load a module ($LOAD) 13 
toad only (form Ht) 16 
load parameter list description 16 
load with find (form!) 13 
log 
definition 9 
linkage to the system 12 
Parameter list for message on system 11 
log support, system 9 
log, displacements for system 12 


machine configuration 4 macro instruction (continued) 


macro instruction $TIOB (timer 1OB) 19 
$ALOC lallocate space) 23 $TOD (return time and date) 20 
$CHK (check I/O completion) 26 $TRAN (interface translate routine) 18 
$CKL (generate checklist) 25 $TRL {translate parameter list) 17 
$CLOS (prepare device for termination) 26 $TRTB (translate table) 18 
SCOMN (COMMON equates) 27 $WAIT (wait disk IDS completion) 47 
$CQEP (generate parameter list program function key) 61 $WRTD (write to disk) 47 
$CTLT (control command for tape) 54 $WRTT (write to tape) 54 
$DATE (obtain system date) 19 $WTT (wait tape 1/O completion) 55 
$DTFC (card DTF) 28 $XCTL (load module exchange control) 17 
$DTFD (disk DTF) 36 macro instruction statements (see chapter 2) 
$DTFI (device-independent DTF) 56 macro instructions 
$DTFK (3741 DTF) 48 coding 1 
$DTFO (generate DTF offsets) 27 definitions 1 
$DTFP (printer DTF) 33 deleting 4 
$DTFS (CRT DTF) 58 error codes 67 
$DTFT (tape DTF) 49 listof 5 
$EOJ (end-of-job) 20 sample program 66 
SFIND (find directory entry) 13 summary chart 111 
$FTCH (load module pass control} 16 macro processor 
$GETC (card get interface) 30 overview 2 
SGETD (disk get interface) 40 register usage 7 
$SGETI (device-independent get interface) 57 residence 4 
$GETK (3741 get interface) 48 restrictions 7 
$GETS (get record from CRT/keyboard) 59 main data areas 35 
$GETT (tape get interface) 52 main storage ($SNAP), dump, snap 18 
$GPC (interface reading, punching, and printing cards) 32 message on system log, parameter list for 11 
$IOBD (input/output block disk) 45 MFCM DTF 71 
$IOED (input/output block offsets) 46 MFCUDTF 69 
$LMSG (parameter list message system log) 11 Minimum system configuration 4 
$LOAD (load module} 13 Model 15 translate routine 17 
$LOG (linkage system log) 12 module ($LOAD), loada 13 
$LOGD (displacements system log) 12 module and exchange control ($XCTL), loada 17 
$LWTO (parameter list WTO or WTOR) 10 module and pass contro! ($F TCH), loada 16 
SOPEN (prepare an I/O device) 24 multivolume file support 52 


$PFKT (test program function key pressed) 62 

$PFKY (allocate program function key to program) 61 

$PGS (put/get operation CRT data management) 59 

$PUTC (card put interface) 31 

$PUTD (disk put interface) 44 name field, description 1 
$PUTI (device-independent put interface) 57 

$PUTK (3741 put interface) 49 

$SPUTP (printer put interface) 34 

$PUTS (put record CRT data management) 60 


$PUTT (tape put interface) 53 obtain system date (SDATE) 19 
$RDD (read fromdisk) 46 OCL for macro processor 63 
$RDT (read from tape) 53 offsets 

SREAD (linkage system reader function) 9 device and access methods 27 
$RIT (return interval time) 20 disk 41 

$RLSD (system reader parameter list offsets) 8 system log parameter list 10, 12 
$RLST (system reader parameter) 8 open routine 

$ROLL (rotlout/roilin linkage) 12 input 24 

$SIT (set interval timer) 19 output 24 

$SNAP (snap dump main storage) 18 operand 1 


operation code 1 
operation 
check routine 26 
translate routine 17 
option 1 
output 
close routine 26 
open routine 24 
Qutput devices, supported 4 


Index 123 


Pack, system 4 
Parameter list 

find macro 13 

load description 16 

log and/or message to operator 11 

program function key 61 

support system log 10 

system log message 11 

system logWTO 10 

system reader 8 

translate routine 17 

write to operator 10 
pass control ($F TCH), load a module and 
prepare a device for termination ($CLOS) 
prepare an 1/O device (SOPEN) 24 
printer data management interface 34 
Printer DTF description 75 
printer support 33 
Processor, macro ($SMPXDV) 2 
program control 

exchange 17 

Pass 16 
program function key 

muitiple usage 62 

Parameter list 61 


request 61 
support 61 
test 62 


program, sample 63 
programming considerations 7 
put 

card 31 

CRT/keyboard 60 

device-independent 57 

disk 41 

Printer 34 

tape 53 

3741 49 


put a record to the CRT via data management ($PUTS) 


Q-byte 46 


R-byte settings 111 
read 
card ($GPC) 32 
disk ($RDD) 46 
tape ($RDT) 53 
reader support, system 8 
record length 
device-independent 56 
tape 50 
register usage 7 
residence of macro processor 4 
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restrictions 

allocate space 23 

labels (see label restrictions} 

Macro processor 7 

main data areas 35 

rollout 12 

simulation areas 35 

telecommunications 23 
return codes, system reader function 8,9 
return interval time ($RIT) 20 
return time and date ($TOD) 20 
rollout routine 12 
rollout/rollin linkage (SRDLL) 12 
routines, data management 

card 30, 31 

CRT/keyboard 59 

device independent 57 


disk 40, 41 
printer 34 
tape 52,53 


tape-basic 53,54 


sample program 63 
macro instructions used 66 
OCL 63 
Purpose of the 63 
termination 63 
SCP 7 
SCP support, general 12 
set interval timer ($SIT) 19 
simulation areas 35 
snap dump main storage ($SSNAP) 18 
statement,OCL 62 
supported devices 4 
system configuration, minimum 4 
system control program (see SCP) 
systemdate 19 
system input devices 4 
system log support 9 
system pack 4 
system reader 
devices 8 
function 9 
Parameter list 8 
parameter list offsets ($RLSD) 8 
support 8 
system services macros 7 


tape data management interface 
control commands 54 
get 52 
put 53 
read 53 
write 54 
tape data management routines 52 
tape data management routines (basic) 53 
table of extents, disk 37 
table, translate 17 
tape buffer storage requirements 50 
tape device support 49 
tape routines 
control 54 
get 52 
put 53 
read 53 
wait 55 
write 54 
terminate device 26 
test for program function key pressed ($PFKT) 62 
time and date, return 20 
timer 1OB (see {OB) 
timer, setting 19 
translate parameter list (STRL) 17 
translate routine operation 17 
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